@cosmicdrift/kumiko-framework 0.1.0

package/src/random/words.ts

@@ -0,0 +1,392 @@
+// Wortlisten für human-readable Resource-Slugs (Tenant-Keys, Webhook-
+// Subscribers, API-Key-Display-Names, Test-Fixtures). Heroku/Docker-
+// Style — adjective + noun produzieren aussprechbare, merkbare,
+// PII-freie Identifier.
+//
+// Auswahl-Kriterien:
+//   - Emotional-neutral und professionell (kein "fluffy", "sneaky")
+//   - Keine Tiernamen (Heroku-Cliché)
+//   - Keine Personennamen (cultural appropriation, prominenten-collision)
+//   - Keine Themen-Cluster (kein Wetter-only, kein Geographie-only)
+//   - Lowercase, ASCII-only, keine Bindestriche im Wort selbst
+//   - 4-8 Buchstaben pro Wort (kompakter Slug)
+//   - Aussprechbar in Deutsch UND Englisch (User-Telefon-Support)
+//   - Keine Wörter mit ambiguer Bedeutung in Englisch+Deutsch
+//
+// 150 × 150 = 22.500 saubere Kombinationen — bei einer Standard-
+// Hashing-Kollision (Birthday-Bound) reicht das für ~150 Tenants ohne
+// Suffix. Drüber kommt der Suffix-Pfad in generateUniqueName.
+//
+// Erweiterung: weitere Wörter unten anhängen reicht (sortiert ist
+// hilfreich für Reviews aber nicht erforderlich). Caller können auch
+// eigene Listen via generateUniqueName({ adjectives, nouns }) reichen.
+
+export const ADJECTIVES: readonly string[] = Object.freeze([
+  "agile",
+  "amber",
+  "ample",
+  "ardent",
+  "aurora",
+  "balanced",
+  "bold",
+  "brave",
+  "breezy",
+  "bright",
+  "brisk",
+  "calm",
+  "candid",
+  "cheery",
+  "chosen",
+  "clear",
+  "clever",
+  "clipped",
+  "cobalt",
+  "cool",
+  "coral",
+  "cosmic",
+  "crimson",
+  "crisp",
+  "crystal",
+  "daring",
+  "dawning",
+  "deep",
+  "deft",
+  "diamond",
+  "distant",
+  "dreamy",
+  "earnest",
+  "easy",
+  "elder",
+  "elegant",
+  "elite",
+  "emerald",
+  "endless",
+  "even",
+  "fabled",
+  "fair",
+  "famous",
+  "fancy",
+  "fearless",
+  "fertile",
+  "fiery",
+  "fine",
+  "firm",
+  "first",
+  "flora",
+  "fluent",
+  "fluid",
+  "fond",
+  "forward",
+  "frank",
+  "free",
+  "fresh",
+  "frosty",
+  "gallant",
+  "gentle",
+  "gilded",
+  "glad",
+  "gleaming",
+  "golden",
+  "gracious",
+  "grand",
+  "great",
+  "happy",
+  "hardy",
+  "hearty",
+  "honest",
+  "humble",
+  "iconic",
+  "idle",
+  "imperial",
+  "ivory",
+  "jade",
+  "jolly",
+  "joyful",
+  "keen",
+  "kind",
+  "lasting",
+  "level",
+  "liberal",
+  "light",
+  "lively",
+  "loyal",
+  "lucid",
+  "lucky",
+  "lush",
+  "main",
+  "marble",
+  "mellow",
+  "merry",
+  "mighty",
+  "mild",
+  "modern",
+  "modest",
+  "mossy",
+  "mystic",
+  "neat",
+  "nimble",
+  "noble",
+  "northern",
+  "ocean",
+  "olive",
+  "open",
+  "ornate",
+  "patient",
+  "peaceful",
+  "perfect",
+  "polished",
+  "prime",
+  "pristine",
+  "proud",
+  "prudent",
+  "pure",
+  "quaint",
+  "quick",
+  "quiet",
+  "radiant",
+  "rapid",
+  "ready",
+  "regal",
+  "rich",
+  "ripe",
+  "robust",
+  "rolling",
+  "royal",
+  "ruby",
+  "rugged",
+  "rustic",
+  "saffron",
+  "sage",
+  "scenic",
+  "secret",
+  "serene",
+  "shining",
+  "silent",
+  "silver",
+  "simple",
+  "sincere",
+  "sleek",
+  "smooth",
+  "solar",
+  "solid",
+  "sound",
+  "sparkling",
+  "stable",
+  "starry",
+  "steady",
+  "stellar",
+  "sterling",
+  "still",
+  "stoic",
+  "strong",
+  "sturdy",
+  "subtle",
+  "sunny",
+  "supple",
+  "sweet",
+  "swift",
+  "tame",
+  "tender",
+  "thrifty",
+  "tidy",
+  "tireless",
+  "tough",
+  "tranquil",
+  "trusted",
+  "trusty",
+  "ultra",
+  "valiant",
+  "vast",
+  "verdant",
+  "vibrant",
+  "vivid",
+  "warm",
+  "wavy",
+  "wild",
+  "willowy",
+  "windy",
+  "winged",
+  "winter",
+  "wise",
+  "witty",
+  "worthy",
+  "young",
+  "zealous",
+  "zen",
+]);
+
+export const NOUNS: readonly string[] = Object.freeze([
+  "anchor",
+  "arch",
+  "atlas",
+  "atrium",
+  "aurora",
+  "badge",
+  "banner",
+  "bastion",
+  "bay",
+  "beacon",
+  "blossom",
+  "bloom",
+  "bonfire",
+  "bramble",
+  "breeze",
+  "bridge",
+  "brook",
+  "cabin",
+  "canopy",
+  "canyon",
+  "carbon",
+  "cascade",
+  "castle",
+  "cavern",
+  "channel",
+  "chapel",
+  "charter",
+  "cinder",
+  "citadel",
+  "clearing",
+  "cliff",
+  "cloud",
+  "clover",
+  "coast",
+  "comet",
+  "compass",
+  "copper",
+  "cottage",
+  "court",
+  "cove",
+  "creek",
+  "crest",
+  "current",
+  "dawn",
+  "delta",
+  "dock",
+  "dome",
+  "door",
+  "dune",
+  "dusk",
+  "eagle",
+  "echo",
+  "ember",
+  "estate",
+  "estuary",
+  "ether",
+  "falcon",
+  "falls",
+  "field",
+  "fjord",
+  "flame",
+  "flora",
+  "forest",
+  "forge",
+  "fortress",
+  "fountain",
+  "garden",
+  "gate",
+  "gateway",
+  "geyser",
+  "glacier",
+  "glade",
+  "glen",
+  "globe",
+  "gorge",
+  "grove",
+  "habitat",
+  "haiku",
+  "hall",
+  "harbor",
+  "harvest",
+  "hatch",
+  "haven",
+  "hearth",
+  "henge",
+  "highland",
+  "hill",
+  "horizon",
+  "isle",
+  "island",
+  "junction",
+  "key",
+  "knoll",
+  "lagoon",
+  "lake",
+  "landing",
+  "lantern",
+  "ledge",
+  "library",
+  "lighthouse",
+  "lily",
+  "lodge",
+  "loft",
+  "manor",
+  "maple",
+  "marble",
+  "market",
+  "marsh",
+  "meadow",
+  "mesa",
+  "mist",
+  "monolith",
+  "moon",
+  "moor",
+  "mosaic",
+  "mountain",
+  "nebula",
+  "oak",
+  "oasis",
+  "obelisk",
+  "ocean",
+  "orchard",
+  "orchid",
+  "outlook",
+  "palace",
+  "passage",
+  "pasture",
+  "patch",
+  "path",
+  "peak",
+  "petal",
+  "pier",
+  "pillar",
+  "pine",
+  "pinnacle",
+  "plateau",
+  "plaza",
+  "pond",
+  "pool",
+  "port",
+  "portal",
+  "prairie",
+  "quarry",
+  "quill",
+  "rainbow",
+  "rampart",
+  "rapids",
+  "ravine",
+  "reef",
+  "ridge",
+  "river",
+  "road",
+  "rock",
+  "saga",
+  "savanna",
+  "scroll",
+  "shore",
+  "signal",
+  "spring",
+  "square",
+  "stable",
+  "station",
+  "stone",
+  "summit",
+  "sunset",
+  "tower",
+  "trail",
+  "valley",
+  "vista",
+  "willow",
+  "window",
+  "yard",
+  "zenith",
+]);

package/src/rate-limit/__tests__/dispatcher-l3.integration.ts

@@ -0,0 +1,111 @@
+import { defineFeature, defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "vitest";
+import { z } from "zod";
+import { createTestUser, setupTestStack, type TestStack, TestUsers } from "../../stack";
+
+// Full-stack L3 proof: a handler with `rateLimit` opt-in is gated by the
+// dispatcher BEFORE its handler-fn runs. After `limit` calls within the
+// window the next call surfaces a 429-shaped error response.
+
+// obj-form handler — proves defineQueryHandler({ ..., rateLimit })
+// reaches the dispatcher with the option intact. Inline-form once
+// silently dropped rateLimit because the spread missed it; obj-form
+// goes through a different path so we need a dedicated test.
+const objFormPing = defineQueryHandler({
+  name: "obj-ping",
+  schema: z.object({}),
+  access: { roles: ["Admin"] },
+  rateLimit: { per: "user", limit: 2, windowSeconds: 60 },
+  handler: async () => ({ ok: true }),
+});
+
+const userOpsLimited = defineFeature("rl-test", (r) => {
+  r.queryHandler("ping", z.object({}), async () => ({ ok: true }), {
+    access: { roles: ["Admin"] },
+    rateLimit: { per: "user", limit: 3, windowSeconds: 60 },
+  });
+  r.queryHandler("open", z.object({}), async () => ({ ok: true }), {
+    // No rateLimit option — proves opt-in: this handler stays
+    // unlimited even though the same user just got blocked on `ping`.
+    access: { roles: ["Admin"] },
+  });
+  r.queryHandler(objFormPing);
+});
+
+let stack: TestStack;
+const admin = TestUsers.admin;
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [userOpsLimited] });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  // Each test starts with a fresh bucket — no carry-over between tests.
+  await stack.redis.flushNamespace();
+});
+
+describe("dispatcher L3 — handler rateLimit opt-in", () => {
+  test("3 calls allowed, 4th call returns rate_limited error response", async () => {
+    for (let i = 0; i < 3; i++) {
+      const ok = await stack.http.queryOk("rl-test:query:ping", {}, admin);
+      expect(ok).toEqual({ ok: true });
+    }
+
+    // The 4th query goes through queryRaw so we can inspect the wire
+    // shape — queryOk would throw on a non-2xx response, masking the
+    // actual error body.
+    const res = await stack.http.query("rl-test:query:ping", {}, admin);
+    expect(res.status).toBe(429);
+    const body = (await res.json()) as { error: { code: string; details?: { bucket?: string } } };
+    expect(body.error.code).toBe("rate_limited");
+    expect(body.error.details?.bucket).toBe(`user:${admin.id}`);
+  });
+
+  test("isolates per user: blocked user does not block other user", async () => {
+    const otherAdmin = createTestUser({ id: 9001, roles: ["Admin"] });
+
+    for (let i = 0; i < 3; i++) {
+      await stack.http.queryOk("rl-test:query:ping", {}, admin);
+    }
+    const blocked = await stack.http.query("rl-test:query:ping", {}, admin);
+    expect(blocked.status).toBe(429);
+
+    const otherOk = await stack.http.queryOk("rl-test:query:ping", {}, otherAdmin);
+    expect(otherOk).toEqual({ ok: true });
+  });
+
+  test("obj-form defineQueryHandler propagates rateLimit through to dispatcher", async () => {
+    // 2 calls allowed (limit on the obj-form definition is 2/min/user).
+    for (let i = 0; i < 2; i++) {
+      const ok = await stack.http.queryOk("rl-test:query:obj-ping", {}, admin);
+      expect(ok).toEqual({ ok: true });
+    }
+    const blocked = await stack.http.query("rl-test:query:obj-ping", {}, admin);
+    // 429 here proves the obj-form path didn't silently drop rateLimit.
+    expect(blocked.status).toBe(429);
+    const body = (await blocked.json()) as {
+      error: { code: string; details?: { limit?: number } };
+    };
+    expect(body.error.code).toBe("rate_limited");
+    expect(body.error.details?.limit).toBe(2);
+  });
+
+  test("same user, different handler without rateLimit: stays unlimited", async () => {
+    for (let i = 0; i < 3; i++) {
+      await stack.http.queryOk("rl-test:query:ping", {}, admin);
+    }
+    const blocked = await stack.http.query("rl-test:query:ping", {}, admin);
+    expect(blocked.status).toBe(429);
+
+    // The "open" handler has no rateLimit declaration → bucket is
+    // independent → admin can still call it freely.
+    for (let i = 0; i < 5; i++) {
+      const ok = await stack.http.queryOk("rl-test:query:open", {}, admin);
+      expect(ok).toEqual({ ok: true });
+    }
+  });
+});

package/src/rate-limit/__tests__/middleware.integration.ts

@@ -0,0 +1,189 @@
+import { Hono } from "hono";
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "vitest";
+import { createTestRedis, type TestRedis } from "../../stack";
+import { authEndpointRateLimit, globalIpRateLimit } from "../middleware";
+import { createRateLimitResolver, type RateLimitResolver } from "../resolver";
+
+let testRedis: TestRedis;
+let resolver: RateLimitResolver;
+
+beforeAll(async () => {
+  testRedis = await createTestRedis();
+});
+
+afterAll(async () => {
+  await testRedis.cleanup();
+});
+
+beforeEach(async () => {
+  await testRedis.flushNamespace();
+  resolver = createRateLimitResolver({
+    redis: testRedis.redis,
+    keyPrefix: "test:rl:",
+  });
+});
+
+describe("globalIpRateLimit (L1)", () => {
+  test("allows up to limit, blocks at limit+1, returns 429 with headers", async () => {
+    const app = new Hono();
+    app.use(
+      "/api/*",
+      globalIpRateLimit({ resolver, limit: 3, windowSeconds: 60, onFailClosed: () => {} }),
+    );
+    app.get("/api/probe", (c) => c.text("ok"));
+
+    const ipHeader = { "x-forwarded-for": "10.0.0.1" };
+    for (let i = 0; i < 3; i++) {
+      const res = await app.request("/api/probe", { headers: ipHeader });
+      expect(res.status).toBe(200);
+      // Allowed responses carry the standard headers so a polite client
+      // can self-throttle without first hitting 429.
+      expect(res.headers.get("X-RateLimit-Limit")).toBe("3");
+      expect(res.headers.get("X-RateLimit-Remaining")).toBe(String(2 - i));
+    }
+    const blocked = await app.request("/api/probe", { headers: ipHeader });
+    expect(blocked.status).toBe(429);
+    expect(blocked.headers.get("Retry-After")).toBeTruthy();
+    expect(blocked.headers.get("X-RateLimit-Limit")).toBe("3");
+    expect(blocked.headers.get("X-RateLimit-Remaining")).toBe("0");
+
+    const body = (await blocked.json()) as { error: { code: string; details: { bucket: string } } };
+    expect(body.error.code).toBe("rate_limited");
+    expect(body.error.details.bucket).toBe("l1:10.0.0.1");
+  });
+
+  test("isolates per IP — different x-forwarded-for has its own bucket", async () => {
+    const app = new Hono();
+    app.use(
+      "/api/*",
+      globalIpRateLimit({ resolver, limit: 2, windowSeconds: 60, onFailClosed: () => {} }),
+    );
+    app.get("/api/probe", (c) => c.text("ok"));
+
+    await app.request("/api/probe", { headers: { "x-forwarded-for": "10.0.0.2" } });
+    await app.request("/api/probe", { headers: { "x-forwarded-for": "10.0.0.2" } });
+    const blocked = await app.request("/api/probe", {
+      headers: { "x-forwarded-for": "10.0.0.2" },
+    });
+    expect(blocked.status).toBe(429);
+
+    const otherIp = await app.request("/api/probe", {
+      headers: { "x-forwarded-for": "10.0.0.99" },
+    });
+    expect(otherIp.status).toBe(200);
+  });
+
+  test("no x-forwarded-for: pass-through (no bucket)", async () => {
+    const app = new Hono();
+    app.use(
+      "/api/*",
+      globalIpRateLimit({ resolver, limit: 1, windowSeconds: 60, onFailClosed: () => {} }),
+    );
+    app.get("/api/probe", (c) => c.text("ok"));
+
+    // No xff header — extractIp returns undefined → middleware skips.
+    // Both calls succeed even though limit=1.
+    const a = await app.request("/api/probe");
+    const b = await app.request("/api/probe");
+    expect(a.status).toBe(200);
+    expect(b.status).toBe(200);
+  });
+
+  test("fail-closed when resolver throws non-RateLimit error (Redis down)", async () => {
+    let onFailCalled = false;
+    const brokenResolver: RateLimitResolver = {
+      check: async () => {
+        throw new Error("ECONNREFUSED");
+      },
+      enforce: async () => {
+        throw new Error("ECONNREFUSED");
+      },
+      peek: async () => {
+        throw new Error("ECONNREFUSED");
+      },
+    };
+
+    const app = new Hono();
+    app.use(
+      "/api/*",
+      globalIpRateLimit({
+        resolver: brokenResolver,
+        limit: 5,
+        windowSeconds: 60,
+        onFailClosed: () => {
+          onFailCalled = true;
+        },
+      }),
+    );
+    app.get("/api/probe", (c) => c.text("ok"));
+
+    const res = await app.request("/api/probe", {
+      headers: { "x-forwarded-for": "10.0.0.5" },
+    });
+    expect(res.status).toBe(503);
+    expect(onFailCalled).toBe(true);
+  });
+});
+
+describe("authEndpointRateLimit (L2)", () => {
+  test("default bucket is ip+path: same IP on different path is independent", async () => {
+    const app = new Hono();
+    app.use(
+      "/auth/*",
+      authEndpointRateLimit({
+        resolver,
+        limit: 2,
+        windowSeconds: 60,
+        onFailClosed: () => {},
+      }),
+    );
+    app.post("/auth/login", (c) => c.text("ok"));
+    app.post("/auth/register", (c) => c.text("ok"));
+
+    const ipHeader = { "x-forwarded-for": "10.0.1.1" };
+    await app.request("/auth/login", { method: "POST", headers: ipHeader });
+    await app.request("/auth/login", { method: "POST", headers: ipHeader });
+    const blocked = await app.request("/auth/login", { method: "POST", headers: ipHeader });
+    expect(blocked.status).toBe(429);
+
+    // Different path → separate bucket — register endpoint not affected.
+    const register = await app.request("/auth/register", { method: "POST", headers: ipHeader });
+    expect(register.status).toBe(200);
+  });
+
+  test("custom extractTarget: account-aware bucketing isolates per email", async () => {
+    const app = new Hono();
+    app.use(
+      "/auth/login",
+      authEndpointRateLimit({
+        resolver,
+        limit: 2,
+        windowSeconds: 60,
+        extractTarget: async (c) => {
+          // Real-world: parse JSON body for `email`. Tests pass the
+          // email as a header for simplicity (body-stream consumption
+          // mid-middleware needs a body-shim that's out of scope here).
+          return c.req.header("x-account") ?? undefined;
+        },
+        onFailClosed: () => {},
+      }),
+    );
+    app.post("/auth/login", (c) => c.text("ok"));
+
+    const ipHeader = { "x-forwarded-for": "10.0.1.5" };
+    const reqA = (acc: string) =>
+      app.request("/auth/login", {
+        method: "POST",
+        headers: { ...ipHeader, "x-account": acc },
+      });
+
+    await reqA("user-a");
+    await reqA("user-a");
+    const blockedA = await reqA("user-a");
+    expect(blockedA.status).toBe(429);
+
+    // Same IP, different account → fresh bucket
+    const otherAcc = await reqA("user-b");
+    expect(otherAcc.status).toBe(200);
+  });
+});