Add hosted captun.sh rate limits

src/worker.ts

@@ -11,14 +11,36 @@ import {
 
 type CaptunEnv = {
   CaptunServerShard: DurableObjectNamespace<CaptunServerShard>;
+  HostedRateLimiter?: DurableObjectNamespace<HostedRateLimiter>;
   CAPTUN_SECRET?: string;
   SHARD_COUNT?: string;
   CUSTOM_HOSTNAME?: string;
+  HOSTED_RATE_LIMIT_WINDOW_SECONDS?: string;
+  HOSTED_CONNECTS_PER_IP_PER_WINDOW?: string;
+  HOSTED_REQUESTS_PER_IP_PER_WINDOW?: string;
+  HOSTED_REQUESTS_PER_TUNNEL_PER_WINDOW?: string;
+  HOSTED_RATE_LIMIT_DISABLED?: string;
 };
 
 /** Set by the top-level Worker on the WebSocket-upgrade request so the DO knows the tunnel. */
 const TUNNEL_NAME_HEADER = "x-captun-tunnel-name";
 
+const DEFAULT_HOSTED_RATE_LIMIT_WINDOW_SECONDS = 60;
+const DEFAULT_HOSTED_CONNECTS_PER_IP_PER_WINDOW = 30;
+const DEFAULT_HOSTED_REQUESTS_PER_IP_PER_WINDOW = 600;
+const DEFAULT_HOSTED_REQUESTS_PER_TUNNEL_PER_WINDOW = 1200;
+
+type HostedRateLimitKind = "connect" | "request";
+
+type HostedRateLimitInput = { limit: number; windowSeconds: number };
+
+type HostedRateLimitResult = { ok: true } | { ok: false; limit: number; retryAfterSeconds: number };
+
+type HostedRateLimitBucket = {
+  count: number;
+  resetAt: number;
+};
+
 /**
  * A shard Durable Object owns many named tunnels.
  *
@@ -71,8 +93,34 @@ export class CaptunServerShard extends DurableObject<CaptunEnv> {
   }
 }
 
+export class HostedRateLimiter extends DurableObject<CaptunEnv> {
+  private bucket: HostedRateLimitBucket | undefined;
+
+  check(input: HostedRateLimitInput): HostedRateLimitResult {
+    const now = Date.now();
+    const bucket = this.activeBucket(now, now + input.windowSeconds * 1000);
+    if (bucket.count >= input.limit) {
+      return {
+        ok: false,
+        limit: input.limit,
+        retryAfterSeconds: Math.max(1, Math.ceil((bucket.resetAt - now) / 1000)),
+      };
+    }
+
+    bucket.count++;
+    return { ok: true };
+  }
+
+  private activeBucket(now: number, resetAt: number) {
+    if (this.bucket && this.bucket.resetAt > now) return this.bucket;
+    const bucket = { count: 0, resetAt };
+    this.bucket = bucket;
+    return bucket;
+  }
+}
+
 export default {
-  fetch(request: Request, env: CaptunEnv): Response | Promise<Response> {
+  async fetch(request: Request, env: CaptunEnv): Promise<Response> {
     const hostedResponse = hostedCaptunResponse(request, env);
     if (hostedResponse) return hostedResponse;
 
@@ -98,11 +146,27 @@ export default {
     const forwarded = new Request(url, request);
 
     if (forwardedPath === "/__captun-connect") {
+      const rateLimited = await hostedRateLimitResponse({
+        env,
+        request,
+        tunnelName,
+        kind: "connect",
+      });
+      if (rateLimited) return rateLimited;
+
       const headers = new Headers(forwarded.headers);
       headers.set(TUNNEL_NAME_HEADER, tunnelName);
       return shard.fetch(new Request(forwarded, { headers }));
     }
 
+    const rateLimited = await hostedRateLimitResponse({
+      env,
+      request,
+      tunnelName,
+      kind: "request",
+    });
+    if (rateLimited) return rateLimited;
+
     // Advertise the canonical tunnel URL back to the tunnel client. The CLI
     // reads this so it doesn't have to mirror the Worker's routing convention.
     const tunnelUrl = getTunnelUrl({
@@ -116,6 +180,111 @@ export default {
   },
 } satisfies ExportedHandler<CaptunEnv>;
 
+async function hostedRateLimitResponse(input: {
+  env: CaptunEnv;
+  request: Request;
+  tunnelName: string;
+  kind: HostedRateLimitKind;
+}): Promise<Response | undefined> {
+  if (input.env.CUSTOM_HOSTNAME !== HOSTED_CAPTUN_HOSTNAME) return undefined;
+  if (!input.env.HostedRateLimiter) {
+    if (input.env.HOSTED_RATE_LIMIT_DISABLED === "1") return undefined;
+    return new Response("Hosted rate limiter is not configured\n", {
+      status: 503,
+      headers: {
+        "content-type": "text/plain; charset=utf-8",
+        "cache-control": "no-store",
+      },
+    });
+  }
+
+  const config = hostedRateLimitConfig(input.env);
+  const checks = hostedRateLimitChecks({
+    kind: input.kind,
+    clientKey: hostedClientKey(input.request),
+    tunnelName: input.tunnelName,
+    config,
+  });
+  for (const check of checks) {
+    const limiter = input.env.HostedRateLimiter.getByName(hostedRateLimiterName(check.key));
+    const result = await limiter.check({
+      limit: check.limit,
+      windowSeconds: config.windowSeconds,
+    });
+    if (!result.ok) return hostedRateLimitedResponse(result);
+  }
+
+  return undefined;
+}
+
+function hostedRateLimitedResponse(result: Extract<HostedRateLimitResult, { ok: false }>) {
+  return new Response(`Rate limit exceeded. Try again in ${result.retryAfterSeconds}s.\n`, {
+    status: 429,
+    headers: {
+      "content-type": "text/plain; charset=utf-8",
+      "cache-control": "no-store",
+      "retry-after": String(result.retryAfterSeconds),
+      "x-captun-rate-limit": String(result.limit),
+    },
+  });
+}
+
+function hostedClientKey(request: Request) {
+  return request.headers.get("cf-connecting-ip") || "unknown";
+}
+
+function hostedRateLimitChecks(input: {
+  kind: HostedRateLimitKind;
+  clientKey: string;
+  tunnelName: string;
+  config: ReturnType<typeof hostedRateLimitConfig>;
+}) {
+  if (input.kind === "connect") {
+    return [{ key: `connect:ip:${input.clientKey}`, limit: input.config.connectsPerIp }];
+  }
+
+  return [
+    { key: `request:ip:${input.clientKey}`, limit: input.config.requestsPerIp },
+    { key: `request:tunnel:${input.tunnelName}`, limit: input.config.requestsPerTunnel },
+  ];
+}
+
+function hostedRateLimiterName(key: string) {
+  let hash = 2166136261;
+  for (let index = 0; index < key.length; index++) {
+    hash ^= key.charCodeAt(index);
+    hash = Math.imul(hash, 16777619);
+  }
+  return `bucket-${(hash >>> 0).toString(36)}`;
+}
+
+function hostedRateLimitConfig(env: CaptunEnv) {
+  return {
+    windowSeconds: positiveInteger(
+      env.HOSTED_RATE_LIMIT_WINDOW_SECONDS,
+      DEFAULT_HOSTED_RATE_LIMIT_WINDOW_SECONDS,
+    ),
+    connectsPerIp: positiveInteger(
+      env.HOSTED_CONNECTS_PER_IP_PER_WINDOW,
+      DEFAULT_HOSTED_CONNECTS_PER_IP_PER_WINDOW,
+    ),
+    requestsPerIp: positiveInteger(
+      env.HOSTED_REQUESTS_PER_IP_PER_WINDOW,
+      DEFAULT_HOSTED_REQUESTS_PER_IP_PER_WINDOW,
+    ),
+    requestsPerTunnel: positiveInteger(
+      env.HOSTED_REQUESTS_PER_TUNNEL_PER_WINDOW,
+      DEFAULT_HOSTED_REQUESTS_PER_TUNNEL_PER_WINDOW,
+    ),
+  };
+}
+
+function positiveInteger(value: string | undefined, fallback: number) {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 1) return fallback;
+  return parsed;
+}
+
 function hostedCaptunResponse(request: Request, env: CaptunEnv): Response | undefined {
   if (env.CUSTOM_HOSTNAME !== HOSTED_CAPTUN_HOSTNAME) return undefined;
 

tasks/hosted-rate-limits.md

@@ -0,0 +1,33 @@
+---
+status: review
+size: medium
+---
+
+# Hosted captun.sh rate limits
+
+Status summary: First hosted throttling slice is implemented and locally verified. It adds hosted-only connect and forwarded-request limits with configurable Worker vars; ownership, paid/custom names, and deeper abuse controls remain follow-up work.
+
+## First hosted throttling slice
+
+- [x] Add a hosted-only rate-limiter Durable Object. _`HostedRateLimiter` is bound in `wrangler.jsonc` and only consulted when `CUSTOM_HOSTNAME=captun.sh`._
+- [x] Limit tunnel connect attempts per client IP. _`__captun-connect` requests check `connect:ip:<client>` before shard dispatch._
+- [x] Limit forwarded HTTP requests per client IP and per tunnel name. _Forwarded hosted requests check both `request:ip:<client>` and `request:tunnel:<name>` buckets._
+- [x] Return useful `429` responses. _Hosted throttles return plain text with `Retry-After`, `cache-control: no-store`, and `x-captun-rate-limit`._
+- [x] Make limits configurable by Worker vars. _Window and connect/IP/tunnel limits are controlled by `HOSTED_\*_PER_WINDOW` vars with public-service defaults._
+- [x] Cover limits in Miniflare tests. _`test/worker.test.ts` covers connect, per-IP request, per-tunnel request, and self-hosted bypass behavior._
+- [ ] Deploy to `captun-public` after merge-ready checks. _Not deployed yet; this stacked PR should deploy after review or on explicit request._
+
+## Follow-up safety work
+
+- [ ] Add tunnel ownership tokens so a different anonymous client cannot evict an active tunnel. _This should return `409` for conflicting reconnects rather than silently replacing the active client._
+- [ ] Add active tunnel caps and reconnect-churn limits. _Likely needs a global-ish Durable Object keyed separately from the shard count._
+- [ ] Add request body, response, and in-flight request caps. _Protect against tunnels used for bulk transfer or resource exhaustion._
+- [ ] Add Cloudflare-native Rate Limiting bindings where available. _Use edge throttles for cheaper rejection before Durable Objects wake up._
+- [ ] Add observability for 429s, high-volume IPs, high-volume tunnel names, and emergency shutdowns. _Needed before the public hosted service is advertised._
+
+## Implementation Notes
+
+- 2026-05-23: Initial unsafe hosted service is intentionally live but obscure. This task starts the first throttling layer before publicising `captun.sh`.
+- 2026-05-24: Implemented fixed-window in-memory buckets in hosted rate-limiter Durable Objects named by hashed bucket key. This is intentionally a first abuse guardrail, not billing-grade quota accounting.
+- 2026-05-24: Review follow-up changed the limiter to fail closed when the binding is missing, added an explicit `HOSTED_RATE_LIMIT_DISABLED=1` escape hatch, and stopped trusting spoofable forwarded-IP headers.
+- 2026-05-24: Verified with `pnpm run check`, `pnpm test`, `pnpm run build`, and `CAPTUN_PUBLIC_E2E=1 pnpm vitest run test/public-hosted.test.ts` after retrying one transient live WebSocket-open failure.

test/miniflare.ts

@@ -52,6 +52,7 @@ export function createCaptunWorkerFixture(bindings: Record<string, string>) {
     entryPoint: "src/worker.ts",
     durableObjects: {
       CaptunServerShard: { className: "CaptunServerShard" },
+      HostedRateLimiter: { className: "HostedRateLimiter" },
     },
     bindings,
   });