@cosmicdrift/kumiko-framework 1.0.0 → 2.0.0

package/src/api/__tests__/batch.integration.test.ts

@@ -1,6 +1,7 @@
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { seedRow } from "@cosmicdrift/kumiko-framework/testing";
 import { z } from "zod";
+import type { TableColumns } from "../../db/dialect";
 import { createEventStoreExecutor } from "../../db/event-store-executor";
 import { asRawClient, selectMany } from "../../db/query";
 import { buildEntityTable } from "../../db/table-builder";
@@ -14,6 +15,7 @@ import {
   type SaveContext,
 } from "../../engine";
 import { UnprocessableError, writeFailure } from "../../errors";
+import { RedisKeys } from "../../pipeline/redis-keys";
 import { setupTestStack, type TestStack, TestUsers, unsafeCreateEntityTable } from "../../stack";
 
 // Entity: a simple "item" with name + counter
@@ -36,7 +38,9 @@ const auditEntity = createEntity({
     itemId: createTextField({ required: true }),
   },
 });
-const auditTable = buildEntityTable("audit", auditEntity);
+// Brand (#742) is compile-time-only; the postSave hook writes this sink via method-form,
+// so hold it at the unbranded TableColumns view (identical runtime shape).
+const auditTable: TableColumns = buildEntityTable("audit", auditEntity);
 
 // Hook invocation logs — reset per test. Captures which phase each hook saw.
 const inTxHookLog: Array<{ id: EntityId; name: string }> = [];
@@ -78,9 +82,9 @@ const itemFeature = defineFeature("batch", (r) => {
   );
 
   // Entity hook: inTransaction — records in memory
-  r.entityHook(
+  r.hook(
     "postSave",
-    item,
+    { allOf: item },
     async (result: SaveContext) => {
       inTxHookLog.push({ id: result.id, name: (result.data["name"] as string) ?? "" });
     },
@@ -89,43 +93,43 @@ const itemFeature = defineFeature("batch", (r) => {
 
   // Entity hook: inTransaction — writes to DB via ctx.db (the tx-scoped TenantDb).
   // Proves that hook DB writes roll back with the main transaction on failure.
-  r.entityHook(
+  r.hook(
     "postSave",
-    item,
+    { allOf: item },
     async (result, ctx) => {
-      if (!ctx.db) return;
+      if (!ctx.db || !("insertOne" in ctx.db)) return;
       await ctx.db.insertOne(auditTable, { action: "item_saved", itemId: result.id });
     },
     { phase: HookPhases.inTransaction },
   );
 
   // Entity hook: afterCommit — records in memory (default phase)
-  r.entityHook("postSave", item, async (result: SaveContext) => {
+  r.hook("postSave", { allOf: item }, async (result: SaveContext) => {
     afterCommitHookLog.push({ id: result.id, name: (result.data["name"] as string) ?? "" });
   });
 
   // Entity hook: afterCommit — may throw, used to verify error isolation
-  r.entityHook("postSave", item, async () => {
+  r.hook("postSave", { allOf: item }, async () => {
     if (afterCommitShouldThrow) throw new Error("afterCommit_boom");
   });
 
   // Entity hook: afterCommit — runs AFTER the throwing one. Used to prove the
   // next hooks still fire despite the earlier failure.
-  r.entityHook("postSave", item, async (result: SaveContext) => {
+  r.hook("postSave", { allOf: item }, async (result: SaveContext) => {
     afterCommitThirdHookRan.push((result.data["name"] as string) ?? "");
   });
 
   // Two hooks used by the parallelism test. Each records its start+end
   // timestamps so the assertion can compare intervals rather than elapsed
   // wall-clock time (which is timing-flaky on loaded CI boxes).
-  r.entityHook("postSave", item, async (result: SaveContext) => {
+  r.hook("postSave", { allOf: item }, async (result: SaveContext) => {
     const name = result.data["name"] as string;
     if (!name?.startsWith("slowness-")) return;
     parallelismWindows.push({ hook: "A", start: Date.now() });
     await new Promise((r) => setTimeout(r, 80));
     parallelismWindows.push({ hook: "A", end: Date.now() });
   });
-  r.entityHook("postSave", item, async (result: SaveContext) => {
+  r.hook("postSave", { allOf: item }, async (result: SaveContext) => {
     const name = result.data["name"] as string;
     if (!name?.startsWith("slowness-")) return;
     parallelismWindows.push({ hook: "B", start: Date.now() });
@@ -367,6 +371,92 @@ describe("POST /api/batch", () => {
     expect(inTxHookLog).toHaveLength(1);
     expect(afterCommitHookLog).toHaveLength(1);
   });
+
+  test("idempotency: failed batch is cached — retry returns same error without re-exec", async () => {
+    const requestId = "batch-rid-fail-cache";
+    const commands = [
+      { type: "batch:write:item:create", payload: { name: "should-rollback" } },
+      { type: "batch:write:item:fail", payload: { name: "stop" } },
+    ];
+
+    const first = await stack.http.batch(commands, admin, requestId);
+    const firstBody = await first.json();
+    expect(first.status).toBe(422);
+    expect(firstBody.isSuccess).toBe(false);
+    expect(firstBody.failedIndex).toBe(1);
+    expect(inTxHookLog.map((h) => h.name)).toEqual(["should-rollback"]);
+    expect(await selectMany(stack.db, itemTable)).toHaveLength(0);
+
+    inTxHookLog.length = 0;
+    afterCommitHookLog.length = 0;
+
+    const second = await stack.http.batch(commands, admin, requestId);
+    const secondBody = await second.json();
+    expect(second.status).toBe(422);
+    expect(secondBody.isSuccess).toBe(false);
+    expect(secondBody.failedIndex).toBe(firstBody.failedIndex);
+    // HTTP re-serializes the cached failure with a fresh requestId/timestamp —
+    // pin the stable business fields, not the transport envelope.
+    expect(secondBody.error.code).toBe(firstBody.error.code);
+    expect(secondBody.error.details).toEqual(firstBody.error.details);
+    // Cached path must not re-run commands (hooks stay empty, DB empty)
+    expect(inTxHookLog).toHaveLength(0);
+    expect(afterCommitHookLog).toHaveLength(0);
+    expect(await selectMany(stack.db, itemTable)).toHaveLength(0);
+  });
+
+  test("idempotency: corrupted cache entry is treated as miss and re-runs", async () => {
+    const requestId = "batch-rid-corrupt";
+    const cacheKey = `${RedisKeys.idempotency}${requestId}`;
+
+    // Prove key-coupling first: seed a well-formed cached entry under the
+    // exact manually-built key and confirm the batch short-circuits on it
+    // (no handler run, no DB write) — if the manual key ever drifts from
+    // what the guard actually reads, this half fails loud instead of the
+    // corrupt-JSON half below silently becoming a no-op cache-miss test.
+    const seeded = { isSuccess: true, results: [{ seeded: true }] };
+    await stack.redis.redis.set(cacheKey, JSON.stringify(seeded), "EX", 60);
+    const cachedRes = await stack.http.batch(
+      [{ type: "batch:write:item:create", payload: { name: "should-not-run" } }],
+      admin,
+      requestId,
+    );
+    expect(await cachedRes.json()).toEqual(seeded);
+    expect(await selectMany(stack.db, itemTable)).toHaveLength(0);
+    expect(inTxHookLog).toHaveLength(0);
+
+    // Now corrupt the same key and confirm it's treated as a miss.
+    await stack.redis.redis.set(cacheKey, "{not-json", "EX", 60);
+
+    const res = await stack.http.batch(
+      [{ type: "batch:write:item:create", payload: { name: "after-corrupt" } }],
+      admin,
+      requestId,
+    );
+    const body = await res.json();
+    expect(res.status).toBe(200);
+    expect(body.isSuccess).toBe(true);
+    expect(await selectMany(stack.db, itemTable)).toHaveLength(1);
+    expect(inTxHookLog.map((h) => h.name)).toEqual(["after-corrupt"]);
+  });
+
+  test("mid-batch handler throw: rolls back prior writes, afterCommit does not fire", async () => {
+    const res = await stack.http.batch(
+      [
+        { type: "batch:write:item:create", payload: { name: "before-throw" } },
+        { type: "batch:write:item:throw", payload: { name: "boom" } },
+        { type: "batch:write:item:create", payload: { name: "never" } },
+      ],
+      admin,
+    );
+    const body = await res.json();
+    expect(body.isSuccess).toBe(false);
+    expect(body.failedIndex).toBe(1);
+    expect(inTxHookLog.map((h) => h.name)).toEqual(["before-throw"]);
+    expect(afterCommitHookLog).toEqual([]);
+    expect(await selectMany(stack.db, itemTable)).toHaveLength(0);
+    expect(await selectMany(stack.db, auditTable)).toHaveLength(0);
+  });
 });
 
 describe("POST /api/write (single write runs in its own transaction)", () => {

package/src/api/__tests__/csrf-constants-sync.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, test } from "bun:test";
+import {
+  CSRF_COOKIE_NAME as DISPATCHER_CSRF_COOKIE_NAME,
+  CSRF_HEADER_NAME as DISPATCHER_CSRF_HEADER_NAME,
+} from "@cosmicdrift/kumiko-dispatcher-live";
+import { CSRF_COOKIE_NAME, CSRF_HEADER_NAME } from "../auth-middleware";
+
+// dispatcher-live keeps its own literal copies of these two constants
+// (see packages/dispatcher-live/src/csrf.ts) because it must stay
+// server-dep-free for browser/React Native bundles. This test is the
+// guardrail that catches drift in CI instead of at runtime.
+describe("CSRF constant sync between framework and dispatcher-live", () => {
+  test("cookie name matches", () => {
+    expect(DISPATCHER_CSRF_COOKIE_NAME).toBe(CSRF_COOKIE_NAME);
+  });
+
+  test("header name matches", () => {
+    expect(DISPATCHER_CSRF_HEADER_NAME).toBe(CSRF_HEADER_NAME);
+  });
+});

package/src/api/__tests__/dispatcher-live.integration.test.ts

@@ -48,6 +48,17 @@ const itemFeature = defineFeature("dlive", (r) => {
     },
     { access: { roles: ["Admin"] } },
   );
+
+  r.streamHandler(
+    "item:tail",
+    z.object({ count: z.number().int().min(0) }),
+    async function* (query) {
+      for (let i = 0; i < query.payload.count; i++) {
+        yield { i, name: `n-${i}` };
+      }
+    },
+    { access: { roles: ["Admin"] } },
+  );
 });
 
 let stack: TestStack;
@@ -215,4 +226,67 @@ describe("dispatcher-live (integration) — full path against Kumiko server", ()
     const rows = await selectMany(stack.db, itemTable);
     expect(rows).toHaveLength(0);
   });
+
+  test("stream: yields every chunk then completes (live dispatcher ↔ POST /api/stream)", async () => {
+    const { fetch, csrfToken } = await buildFetch();
+    const dispatcher = createLiveDispatcher({ fetch, readCsrf: () => csrfToken });
+
+    const chunks: Array<{ i: number; name: string }> = [];
+    for await (const chunk of dispatcher.stream<{ i: number; name: string }>(
+      "dlive:stream:item:tail",
+      { count: 3 },
+    )) {
+      chunks.push(chunk);
+    }
+
+    expect(chunks).toEqual([
+      { i: 0, name: "n-0" },
+      { i: 1, name: "n-1" },
+      { i: 2, name: "n-2" },
+    ]);
+  });
+
+  test("stream: access-denied mid-stream throws mapped DispatcherError (HTTP still 200 SSE)", async () => {
+    // Non-Admin JWT — stream handler requires Admin. Gate fires after SSE
+    // headers are flushed, so the client sees an error frame, not HTTP 403.
+    const csrfToken = generateToken();
+    const guestJwt = await stack.jwt.sign(TestUsers.user);
+    const cookieHeader = `kumiko_auth=${guestJwt}; kumiko_csrf=${csrfToken}`;
+    const fetchImpl = (async (url: unknown, init: RequestInit | undefined) => {
+      return stack.app.request(String(url), {
+        ...(init ?? {}),
+        headers: { ...(init?.headers ?? {}), Cookie: cookieHeader },
+      });
+    }) as unknown as typeof fetch;
+    const dispatcher = createLiveDispatcher({ fetch: fetchImpl, readCsrf: () => csrfToken });
+
+    let thrown: unknown;
+    try {
+      for await (const _ of dispatcher.stream("dlive:stream:item:tail", { count: 1 })) {
+        // should not yield
+      }
+    } catch (e) {
+      thrown = e;
+    }
+    expect(thrown).toMatchObject({ code: "access_denied" });
+  });
+
+  test("stream: validation failure throws mapped DispatcherError from error frame", async () => {
+    const { fetch, csrfToken } = await buildFetch();
+    const dispatcher = createLiveDispatcher({ fetch, readCsrf: () => csrfToken });
+
+    let thrown: unknown;
+    try {
+      for await (const _ of dispatcher.stream("dlive:stream:item:tail", { count: -1 })) {
+        // should not yield
+      }
+    } catch (e) {
+      thrown = e;
+    }
+    expect(thrown).toMatchObject({ code: "validation_error" });
+  });
+
+  // AbortSignal mid-stream against Hono's in-memory `app.request` is
+  // unreliable (body often fully buffered before abort lands). Abort
+  // mapping for stream is covered in dispatcher-live unit tests.
 });

package/src/api/__tests__/jwt.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, it } from "bun:test";
 import * as jose from "jose";
 import type { SessionUser } from "../../engine/types";
-import { createJwtHelper } from "../jwt";
+import { createJwtHelper, loadJwtSecretOrKeyring } from "../jwt";
 
 const SECRET = "test-secret-at-least-32-characters-long-aa";
 const TENANT = "11111111-1111-4111-8111-111111111111";
@@ -83,3 +83,202 @@ describe("createJwtHelper.verify — payload validation (KF-2)", () => {
     await expect(jwt.verify(token)).rejects.toThrow(/sub/);
   });
 });
+
+describe("createJwtHelper — keyring form", () => {
+  it("sets kid in the protected header when signing from a keyring", async () => {
+    const jwt = createJwtHelper({ keys: { v1: SECRET }, signKid: "v1" });
+    const token = await jwt.sign(user);
+    expect(jose.decodeProtectedHeader(token).kid).toBe("v1");
+  });
+
+  it("verifies a keyring-signed token against a string-form helper on the same secret", async () => {
+    const keyringSigner = createJwtHelper({ keys: { v1: SECRET }, signKid: "v1" });
+    const token = await keyringSigner.sign(user);
+
+    const stringVerifier = createJwtHelper(SECRET);
+    const payload = await stringVerifier.verify(token);
+    expect(payload.sub).toBe(user.id);
+  });
+
+  it("omits kid when signing from a plain secret (string form)", async () => {
+    const jwt = createJwtHelper(SECRET);
+    const token = await jwt.sign(user);
+    expect(jose.decodeProtectedHeader(token).kid).toBeUndefined();
+  });
+
+  it("verifies a token signed under an old kid after rotating signKid", async () => {
+    const OLD_SECRET = "old-secret-at-least-32-characters-long-aa";
+    const before = createJwtHelper({ keys: { v1: OLD_SECRET }, signKid: "v1" });
+    const token = await before.sign(user);
+
+    const after = createJwtHelper({ keys: { v1: OLD_SECRET, v2: SECRET }, signKid: "v2" });
+    const payload = await after.verify(token);
+    expect(payload.sub).toBe(user.id);
+  });
+
+  it("verifies a legacy no-kid token against a multi-key keyring", async () => {
+    const legacy = createJwtHelper(SECRET);
+    const token = await legacy.sign(user);
+
+    const rotated = createJwtHelper({
+      keys: { v1: "unrelated-secret-32-characters-longg", v2: SECRET },
+      signKid: "v2",
+    });
+    const payload = await rotated.verify(token);
+    expect(payload.sub).toBe(user.id);
+  });
+
+  it("rejects a token whose kid is not in the keyring", async () => {
+    const signer = createJwtHelper({ keys: { v1: SECRET }, signKid: "v1" });
+    const token = await signer.sign(user);
+
+    const verifier = createJwtHelper({ keys: { v2: SECRET }, signKid: "v2" });
+    await expect(verifier.verify(token)).rejects.toThrow(/kid/);
+  });
+
+  it("throws at creation when signKid is not present in the keyring", () => {
+    expect(() => createJwtHelper({ keys: { v1: SECRET }, signKid: "v2" })).toThrow(/signKid/);
+  });
+});
+
+describe("loadJwtSecretOrKeyring", () => {
+  it("no JWT_SECRET_V<n> → falls back to plain JWT_SECRET", () => {
+    expect(loadJwtSecretOrKeyring({ JWT_SECRET: SECRET })).toBe(SECRET);
+  });
+
+  it("neither JWT_SECRET_V<n> nor JWT_SECRET set → throws", () => {
+    expect(() => loadJwtSecretOrKeyring({})).toThrow(/JWT_SECRET not set/);
+  });
+
+  it("JWT_SECRET_V1 + JWT_SECRET_CURRENT_VERSION=1 → single-key keyring, signKid v1", () => {
+    expect(
+      loadJwtSecretOrKeyring({
+        JWT_SECRET_V1: SECRET,
+        JWT_SECRET_CURRENT_VERSION: "1",
+      }),
+    ).toEqual({ keys: { v1: SECRET }, signKid: "v1" });
+  });
+
+  it("rotation: two versions, current-version picks the sign key, both stay verifiable", () => {
+    const OLD_SECRET = "old-secret-at-least-32-characters-long!!";
+    expect(
+      loadJwtSecretOrKeyring({
+        JWT_SECRET_V1: OLD_SECRET,
+        JWT_SECRET_V2: SECRET,
+        JWT_SECRET_CURRENT_VERSION: "2",
+      }),
+    ).toEqual({ keys: { v1: OLD_SECRET, v2: SECRET }, signKid: "v2" });
+  });
+
+  it("JWT_SECRET_V<n> present but JWT_SECRET_CURRENT_VERSION missing → throws", () => {
+    expect(() => loadJwtSecretOrKeyring({ JWT_SECRET_V1: SECRET })).toThrow(
+      /JWT_SECRET_CURRENT_VERSION not set/,
+    );
+  });
+
+  it("JWT_SECRET_CURRENT_VERSION points at a version with no matching JWT_SECRET_V<n> → throws", () => {
+    expect(() =>
+      loadJwtSecretOrKeyring({
+        JWT_SECRET_V1: SECRET,
+        JWT_SECRET_CURRENT_VERSION: "2",
+      }),
+    ).toThrow(/not present in the keyring/);
+  });
+
+  it("kumiko-framework#1308: plain JWT_SECRET carries over as a verify-only legacy key once a keyring is adopted", () => {
+    // Adopting rotation for the first time doesn't unset JWT_SECRET (it still
+    // signs the separate password-reset/email-verification HMAC family) —
+    // and sessions signed before adoption have no `kid`, so they must keep
+    // verifying against this exact value, not get orphaned the moment
+    // JWT_SECRET_V1 shows up.
+    const PLAIN_SECRET = "pre-rotation-plain-secret-32-chars-long!!";
+    expect(
+      loadJwtSecretOrKeyring({
+        JWT_SECRET: PLAIN_SECRET,
+        JWT_SECRET_V1: SECRET,
+        JWT_SECRET_CURRENT_VERSION: "1",
+      }),
+    ).toEqual({ keys: { v1: SECRET, legacy: PLAIN_SECRET }, signKid: "v1" });
+  });
+
+  it("kumiko-framework#1308: legacy JWT_SECRET never becomes the sign key, only ever verify-only", () => {
+    const PLAIN_SECRET = "pre-rotation-plain-secret-32-chars-long!!";
+    const keyring = loadJwtSecretOrKeyring({
+      JWT_SECRET: PLAIN_SECRET,
+      JWT_SECRET_V1: SECRET,
+      JWT_SECRET_CURRENT_VERSION: "1",
+    });
+    expect(typeof keyring).not.toBe("string");
+    expect((keyring as { signKid: string }).signKid).toBe("v1");
+  });
+
+  it("kumiko-framework#1308: no plain JWT_SECRET set alongside a keyring → no legacy key added", () => {
+    expect(
+      loadJwtSecretOrKeyring({
+        JWT_SECRET_V1: SECRET,
+        JWT_SECRET_CURRENT_VERSION: "1",
+      }),
+    ).toEqual({ keys: { v1: SECRET }, signKid: "v1" });
+  });
+
+  it("plain JWT_SECRET under 32 chars → throws", () => {
+    expect(() => loadJwtSecretOrKeyring({ JWT_SECRET: "too-short" })).toThrow(
+      /JWT_SECRET must be ≥32 chars/,
+    );
+  });
+
+  it("JWT_SECRET_V<n> under 32 chars → throws (bypasses the env-schema check otherwise)", () => {
+    expect(() =>
+      loadJwtSecretOrKeyring({
+        JWT_SECRET_V1: "too-short",
+        JWT_SECRET_CURRENT_VERSION: "1",
+      }),
+    ).toThrow(/JWT_SECRET_V1 must be ≥32 chars/);
+  });
+
+  it("kumiko-framework#1526: short legacy JWT_SECRET is rejected, not silently carried into the keyring", () => {
+    // Auth-bypass: a short JWT_SECRET carried into keys["legacy"] without a
+    // length check would be offline-bruteforceable — an attacker forges
+    // {alg:"HS256", kid:"legacy"} with arbitrary sub/tenantId/roles and
+    // verifyWithKeyring looks the key up by kid straight from the header.
+    expect(() =>
+      loadJwtSecretOrKeyring({
+        JWT_SECRET: "short",
+        JWT_SECRET_V1: SECRET,
+        JWT_SECRET_CURRENT_VERSION: "1",
+      }),
+    ).toThrow(/JWT_SECRET must be ≥32 chars/);
+  });
+
+  it("kumiko-framework#1308: empty JWT_SECRET_V<n> throws instead of silently falling back to single-secret mode", () => {
+    expect(() =>
+      loadJwtSecretOrKeyring({
+        JWT_SECRET: SECRET,
+        JWT_SECRET_V1: "",
+        JWT_SECRET_CURRENT_VERSION: "1",
+      }),
+    ).toThrow(/JWT_SECRET_V1 is set but empty/);
+  });
+});
+
+describe("createJwtHelper — ttlSeconds", () => {
+  it("defaults to 24h", () => {
+    const jwt = createJwtHelper(SECRET);
+    expect(jwt.ttlSeconds).toBe(24 * 60 * 60);
+  });
+
+  it("exposes a custom ttlSeconds", () => {
+    const jwt = createJwtHelper(SECRET, ISSUER, 60 * 60);
+    expect(jwt.ttlSeconds).toBe(60 * 60);
+  });
+
+  it("signs a token whose exp - iat exactly equals ttlSeconds", async () => {
+    const ttlSeconds = 60 * 60;
+    const jwt = createJwtHelper(SECRET, ISSUER, ttlSeconds);
+    const token = await jwt.sign(user);
+    const claims = jose.decodeJwt(token);
+    expect(claims.exp).toBeDefined();
+    expect(claims.iat).toBeDefined();
+    expect(claims.exp! - claims.iat!).toBe(ttlSeconds);
+  });
+});

package/src/api/__tests__/login-rate-limiter-sweep.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, test } from "bun:test";
+import { createInMemoryLoginRateLimiter } from "../auth-routes";
+
+describe("createInMemoryLoginRateLimiter — sweep + cap", () => {
+  test("sweepExpired removes expired entries before enforceCap can evict a fresh key", async () => {
+    // maxAttempts=1 makes every entry a single-shot probe: a second `check`
+    // on the same key only returns true if the entry was actually removed
+    // from the map (either by expiry+sweep or by enforceCap).
+    const limiter = createInMemoryLoginRateLimiter(1, 50, {
+      maxEntries: 2,
+      sweepThreshold: 2,
+    });
+
+    expect(await limiter.check("old1")).toBe(true);
+    expect(await limiter.check("old2")).toBe(true);
+    // Let both windows expire.
+    await Bun.sleep(60);
+
+    // hits.size (2) >= sweepThreshold (2) → sweepExpired runs first and
+    // clears old1/old2 before "new1" is inserted, so enforceCap never fires.
+    expect(await limiter.check("new1")).toBe(true);
+    expect(await limiter.check("new2")).toBe(true);
+
+    // If enforceCap had run instead of (or before) the sweep, it would have
+    // evicted "new1" as the oldest live entry, and this check would return
+    // true (fresh window) rather than false (still rate-limited).
+    expect(await limiter.check("new1")).toBe(false);
+  });
+
+  test("enforceCap drops the oldest entry when the map exceeds maxEntries", async () => {
+    const limiter = createInMemoryLoginRateLimiter(1, 60_000, {
+      maxEntries: 3,
+      sweepThreshold: 10_000, // never sweep — only the hard cap matters
+    });
+
+    expect(await limiter.check("k1")).toBe(true);
+    expect(await limiter.check("k2")).toBe(true);
+    expect(await limiter.check("k3")).toBe(true);
+    // 4th insert trips enforceCap → drops the oldest entry (k1).
+    expect(await limiter.check("k4")).toBe(true);
+
+    // k1 was dropped — a fresh check starts a new window (allowed).
+    expect(await limiter.check("k1")).toBe(true);
+
+    // k4 must still be alive in the map: a check within its still-open
+    // window is rate-limited (count >= maxAttempts), proving enforceCap
+    // dropped k1 and not k4.
+    expect(await limiter.check("k4")).toBe(false);
+  });
+});

package/src/api/__tests__/pat-scope.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from "bun:test";
+import { patAllows, qnMatches } from "../pat-scope";
+
+describe("qnMatches", () => {
+  it("exact match", () => {
+    expect(qnMatches("credit:query:schedule", "credit:query:schedule")).toBe(true);
+    expect(qnMatches("credit:query:schedule", "credit:query:credit:list")).toBe(false);
+  });
+
+  it("wildcard suffix matches on prefix", () => {
+    expect(qnMatches("credit:write:bauspar:*", "credit:write:bauspar:create")).toBe(true);
+    expect(qnMatches("credit:write:bauspar:*", "credit:write:bauspar:delete")).toBe(true);
+    expect(qnMatches("credit:write:bauspar:*", "credit:write:create")).toBe(false);
+  });
+
+  it("bare wildcard matches everything", () => {
+    expect(qnMatches("*", "anything:at:all")).toBe(true);
+  });
+});
+
+describe("patAllows", () => {
+  const allowed = ["credit:write:create", "credit:write:bauspar:*"];
+
+  it("permits an exact or wildcard-covered type", () => {
+    expect(patAllows(allowed, "credit:write:create")).toBe(true);
+    expect(patAllows(allowed, "credit:write:bauspar:update")).toBe(true);
+  });
+
+  it("denies a type no scope covers", () => {
+    expect(patAllows(allowed, "credit:write:credit:delete")).toBe(false);
+  });
+
+  it("fail-closed on an empty allow-list", () => {
+    expect(patAllows([], "credit:write:create")).toBe(false);
+  });
+});