@cosmicdrift/kumiko-framework 0.1.0

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

@@ -0,0 +1,189 @@
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "vitest";
+import { RateLimitError } from "../../errors";
+import { createTestRedis, type TestRedis } from "../../stack";
+import { createRateLimitResolver, type RateLimitResolver } from "../resolver";
+
+let testRedis: TestRedis;
+let resolver: RateLimitResolver;
+
+// Controllable clock so tests can advance time deterministically without
+// real waits. Production passes Date.now; tests inject this so refill
+// behaviour is observable in milliseconds.
+let mockNowMs: number;
+
+beforeAll(async () => {
+  testRedis = await createTestRedis();
+});
+
+afterAll(async () => {
+  await testRedis.cleanup();
+});
+
+beforeEach(async () => {
+  await testRedis.flushNamespace();
+  mockNowMs = 1_700_000_000_000; // arbitrary fixed start
+  resolver = createRateLimitResolver({
+    redis: testRedis.redis,
+    keyPrefix: "test:rl:",
+    nowMs: () => mockNowMs,
+  });
+});
+
+describe("createRateLimitResolver — token bucket basics", () => {
+  test("first N requests within limit are allowed, N+1 is rejected", async () => {
+    const config = { limit: 5, windowSeconds: 60 };
+    const decisions = [];
+    for (let i = 0; i < 5; i++) {
+      decisions.push(await resolver.check("user:42", config));
+    }
+    expect(decisions.every((d) => d.allowed)).toBe(true);
+    expect(decisions.map((d) => d.remaining)).toEqual([4, 3, 2, 1, 0]);
+
+    const sixth = await resolver.check("user:42", config);
+    expect(sixth.allowed).toBe(false);
+    expect(sixth.remaining).toBe(0);
+    expect(sixth.retryAfterSeconds).toBeGreaterThan(0);
+  });
+
+  test("buckets are isolated by key — different user has fresh bucket", async () => {
+    const config = { limit: 2, windowSeconds: 60 };
+    await resolver.check("user:a", config);
+    await resolver.check("user:a", config);
+    const aBlocked = await resolver.check("user:a", config);
+    expect(aBlocked.allowed).toBe(false);
+
+    const bFirst = await resolver.check("user:b", config);
+    expect(bFirst.allowed).toBe(true);
+    expect(bFirst.remaining).toBe(1);
+  });
+
+  test("refill: after window/2 the bucket has limit/2 tokens back", async () => {
+    const config = { limit: 10, windowSeconds: 10 };
+    // Drain the bucket
+    for (let i = 0; i < 10; i++) await resolver.check("refill:user", config);
+    const drained = await resolver.check("refill:user", config);
+    expect(drained.allowed).toBe(false);
+
+    // Advance 5s = window/2 → ~5 tokens refilled
+    mockNowMs += 5000;
+    const decisions = [];
+    for (let i = 0; i < 5; i++) {
+      decisions.push(await resolver.check("refill:user", config));
+    }
+    expect(decisions.every((d) => d.allowed)).toBe(true);
+
+    // Sixth in this batch should be blocked again — only 5 tokens were refilled.
+    const overshoot = await resolver.check("refill:user", config);
+    expect(overshoot.allowed).toBe(false);
+  });
+
+  test("refill caps at limit — long idle does not exceed bucket size", async () => {
+    const config = { limit: 5, windowSeconds: 10 };
+    await resolver.check("idle:user", config);
+
+    // Advance 10× the window → bucket would overflow without the cap.
+    mockNowMs += 10 * 10 * 1000;
+
+    const decisions = [];
+    for (let i = 0; i < 5; i++) {
+      decisions.push(await resolver.check("idle:user", config));
+    }
+    expect(decisions.every((d) => d.allowed)).toBe(true);
+    const blocked = await resolver.check("idle:user", config);
+    expect(blocked.allowed).toBe(false);
+  });
+});
+
+describe("createRateLimitResolver — cost", () => {
+  test("cost: 5 deducts 5 tokens at once", async () => {
+    const config = { limit: 10, windowSeconds: 60, cost: 5 };
+    const first = await resolver.check("cost:user", config);
+    expect(first.allowed).toBe(true);
+    expect(first.remaining).toBe(5);
+
+    const second = await resolver.check("cost:user", config);
+    expect(second.allowed).toBe(true);
+    expect(second.remaining).toBe(0);
+
+    const third = await resolver.check("cost:user", config);
+    expect(third.allowed).toBe(false);
+  });
+
+  test("cost > limit: never allowed", async () => {
+    const config = { limit: 5, windowSeconds: 60, cost: 10 };
+    const decision = await resolver.check("over:user", config);
+    expect(decision.allowed).toBe(false);
+  });
+});
+
+describe("createRateLimitResolver — concurrency", () => {
+  test("100 parallel requests at limit=10 — exactly 10 are allowed", async () => {
+    const config = { limit: 10, windowSeconds: 60 };
+    // 100 concurrent calls. Lua atomicity → exactly `limit` of them
+    // come back allowed=true; the rest are rejected. No double-spend.
+    const results = await Promise.all(
+      Array.from({ length: 100 }, () => resolver.check("race:user", config)),
+    );
+    const allowedCount = results.filter((d) => d.allowed).length;
+    expect(allowedCount).toBe(10);
+  });
+});
+
+describe("createRateLimitResolver — peek", () => {
+  test("peek returns the same state across consecutive calls — no token deduction", async () => {
+    const config = { limit: 5, windowSeconds: 60 };
+    // Drain 2 tokens via real check() so the bucket is at remaining=3.
+    await resolver.check("peek:user", config);
+    await resolver.check("peek:user", config);
+
+    // Three back-to-back peeks at the SAME wallclock — remaining must
+    // not move. If peek mutated state, each call would deduct/refill
+    // and the numbers would drift.
+    const a = await resolver.peek("peek:user", config);
+    const b = await resolver.peek("peek:user", config);
+    const c = await resolver.peek("peek:user", config);
+    expect(a.remaining).toBe(3);
+    expect(b.remaining).toBe(3);
+    expect(c.remaining).toBe(3);
+
+    // After 100 peeks, the next real check still sees remaining=3-1=2.
+    // Proves peek doesn't shift the refill timestamp either — if it did,
+    // the next refill maths would over-credit and remaining would jump.
+    for (let i = 0; i < 100; i++) await resolver.peek("peek:user", config);
+    const next = await resolver.check("peek:user", config);
+    expect(next.remaining).toBe(2);
+  });
+
+  test("peek on a fresh bucket reports the full limit available", async () => {
+    const config = { limit: 7, windowSeconds: 60 };
+    const decision = await resolver.peek("peek:fresh", config);
+    expect(decision.allowed).toBe(true);
+    expect(decision.remaining).toBe(7);
+    expect(decision.limit).toBe(7);
+    // Fresh bucket → no need to wait for a refill.
+    expect(decision.retryAfterSeconds).toBe(0);
+  });
+});
+
+describe("createRateLimitResolver — enforce", () => {
+  test("enforce throws RateLimitError with the bucket details when blocked", async () => {
+    const config = { limit: 1, windowSeconds: 60 };
+    await resolver.enforce("enf:user", config);
+
+    let thrown: unknown;
+    try {
+      await resolver.enforce("enf:user", config);
+    } catch (e) {
+      thrown = e;
+    }
+    expect(thrown).toBeInstanceOf(RateLimitError);
+    const err = thrown as RateLimitError;
+    expect(err.httpStatus).toBe(429);
+    expect(err.code).toBe("rate_limited");
+    expect(err.details.bucket).toBe("enf:user");
+    expect(err.details.limit).toBe(1);
+    expect(err.details.windowSeconds).toBe(60);
+    expect(err.details.retryAfterSeconds).toBeGreaterThan(0);
+    expect(err.details.resetAt).toMatch(/^\d{4}-\d{2}-\d{2}T/);
+  });
+});

package/src/rate-limit/bucket.ts

@@ -0,0 +1,36 @@
+import type { RateLimitOption, SessionUser } from "../engine/types";
+
+// Build the Redis bucket key for a handler-level rate limit. Format:
+//   <handler>:<dimension-tag>:<dimension-value>
+// Dimension-tag keeps buckets disjoint when the same tenant/user shows up
+// in multiple bucket strategies — `user+handler` and `user` for the same
+// user are independent buckets.
+
+export type BucketContext = {
+  readonly handlerName: string;
+  readonly user: SessionUser;
+  readonly ip: string | undefined;
+};
+
+export type BucketResult =
+  | { readonly kind: "key"; readonly key: string }
+  | { readonly kind: "skip"; readonly reason: string };
+
+export function buildBucketKey(option: RateLimitOption, ctx: BucketContext): BucketResult {
+  switch (option.per) {
+    case "user":
+      return { kind: "key", key: `user:${ctx.user.id}` };
+    case "tenant":
+      return { kind: "key", key: `tenant:${ctx.user.tenantId}` };
+    case "ip":
+      if (!ctx.ip) return { kind: "skip", reason: "no_ip" };
+      return { kind: "key", key: `ip:${ctx.ip}` };
+    case "user+handler":
+      return { kind: "key", key: `user+handler:${ctx.user.id}:${ctx.handlerName}` };
+    case "tenant+handler":
+      return { kind: "key", key: `tenant+handler:${ctx.user.tenantId}:${ctx.handlerName}` };
+    case "ip+handler":
+      if (!ctx.ip) return { kind: "skip", reason: "no_ip" };
+      return { kind: "key", key: `ip+handler:${ctx.ip}:${ctx.handlerName}` };
+  }
+}

package/src/rate-limit/index.ts

@@ -0,0 +1,14 @@
+export { type BucketContext, type BucketResult, buildBucketKey } from "./bucket";
+export {
+  type AuthEndpointRateLimitOptions,
+  authEndpointRateLimit,
+  type GlobalIpRateLimitOptions,
+  globalIpRateLimit,
+} from "./middleware";
+export {
+  createRateLimitResolver,
+  type RateLimitConfig,
+  type RateLimitDecision,
+  type RateLimitResolver,
+  type RateLimitResolverOptions,
+} from "./resolver";

package/src/rate-limit/middleware.ts

@@ -0,0 +1,152 @@
+import type { Context, MiddlewareHandler } from "hono";
+import { requestContext } from "../api/request-context";
+import { RateLimitError, serializeError } from "../errors";
+import type { RateLimitDecision, RateLimitResolver } from "./resolver";
+
+// Hono middleware factories for L1 (Global-IP) and L2 (Auth-Endpoints).
+//
+// Both share the same response shape on 429 — RFC 6585 status, the
+// X-RateLimit-* headers IETF draft uses, and a structured JSON body
+// produced by the central serializeError() so L1/L2/L3 share the
+// `error.code`, `i18nKey`, `details`, `requestId`, `timestamp` envelope.
+//
+// Fail-mode policy (from docs/plans/features/core-rate-limiting.md):
+//   L1/L2 — **fail-closed** when Redis is down. The caller is most
+//           likely an attacker; refusing service is safer than letting
+//           an unbounded flood through.
+//   L3   — fail-open (handled in dispatcher path). App availability
+//           wins for known heavy handlers when Redis blips.
+
+export type GlobalIpRateLimitOptions = {
+  readonly resolver: RateLimitResolver;
+  readonly limit?: number;
+  readonly windowSeconds?: number;
+  // Override IP extraction — useful when behind a non-standard proxy.
+  // Default: x-forwarded-for first hop.
+  readonly extractIp?: (c: Context) => string | undefined;
+  // Hook for ops logging when fail-closed fires (Redis down). Default:
+  // emits to console.error so the misbehaviour is loud at minimum.
+  readonly onFailClosed?: (err: unknown) => void;
+};
+
+export function globalIpRateLimit(opts: GlobalIpRateLimitOptions): MiddlewareHandler {
+  const limit = opts.limit ?? 1000;
+  const windowSeconds = opts.windowSeconds ?? 60;
+  const extractIp = opts.extractIp ?? defaultExtractIp;
+  const onFailClosed = opts.onFailClosed ?? defaultOnFailClosed("l1-global-ip");
+
+  return async (c, next) => {
+    const ip = extractIp(c);
+    if (!ip) {
+      // No IP and no override → can't bucket. Pass-through; deployments
+      // that care about that hardening should pin extractIp explicitly.
+      return next();
+    }
+
+    try {
+      const decision = await opts.resolver.check(`l1:${ip}`, { limit, windowSeconds });
+      if (!decision.allowed) {
+        return respondRateLimited(c, decision, `l1:${ip}`);
+      }
+      setRateLimitHeaders(c, decision);
+    } catch (e) {
+      // Fail-closed: refuse rather than let a flood through with no cap.
+      // resolver.check never throws RateLimitError (only enforce does),
+      // so any throw here is an infrastructure failure (Redis down).
+      onFailClosed(e);
+      return c.json(
+        { error: { code: "rate_limit_unavailable", message: "Rate limiter unavailable" } },
+        503,
+      );
+    }
+    await next();
+  };
+}
+
+export type AuthEndpointRateLimitOptions = {
+  readonly resolver: RateLimitResolver;
+  readonly limit?: number;
+  readonly windowSeconds?: number;
+  // Optional target extractor for account-aware bucketing. When set,
+  // the bucket key is `l2:${ip}:${target}` — adds account isolation on
+  // top of IP. Default: bucket on `l2:${ip}:${path}` (IP + route),
+  // which catches naive IP-flood without consuming the request body.
+  readonly extractTarget?: (c: Context) => string | undefined | Promise<string | undefined>;
+  readonly extractIp?: (c: Context) => string | undefined;
+  readonly onFailClosed?: (err: unknown) => void;
+};
+
+export function authEndpointRateLimit(opts: AuthEndpointRateLimitOptions): MiddlewareHandler {
+  const limit = opts.limit ?? 5;
+  const windowSeconds = opts.windowSeconds ?? 60;
+  const extractIp = opts.extractIp ?? defaultExtractIp;
+  const extractTarget = opts.extractTarget;
+  const onFailClosed = opts.onFailClosed ?? defaultOnFailClosed("l2-auth-endpoints");
+
+  return async (c, next) => {
+    const ip = extractIp(c);
+    if (!ip) return next();
+
+    const target = (await extractTarget?.(c)) ?? c.req.path;
+    const bucket = `l2:${ip}:${target}`;
+
+    try {
+      const decision = await opts.resolver.check(bucket, { limit, windowSeconds });
+      if (!decision.allowed) {
+        return respondRateLimited(c, decision, bucket);
+      }
+      setRateLimitHeaders(c, decision);
+    } catch (e) {
+      onFailClosed(e);
+      return c.json(
+        { error: { code: "rate_limit_unavailable", message: "Rate limiter unavailable" } },
+        503,
+      );
+    }
+    await next();
+  };
+}
+
+function defaultExtractIp(c: Context): string | undefined {
+  const xff = c.req.header("x-forwarded-for");
+  return xff?.split(",")[0]?.trim() || undefined;
+}
+
+function defaultOnFailClosed(label: string): (err: unknown) => void {
+  return (err) => {
+    // Loud by default — fail-closed for an unknown reason is an ops
+    // signal, not something to swallow silently. Production deploys
+    // override this with a structured logger; the default keeps the
+    // noise visible if no logger is wired.
+    // biome-ignore lint/suspicious/noConsole: ops-visible fallback when no logger is wired
+    console.error(`[rate-limit ${label}] fail-closed (refusing request):`, err);
+  };
+}
+
+function setRateLimitHeaders(c: Context, decision: RateLimitDecision): void {
+  c.header("X-RateLimit-Limit", String(decision.limit));
+  c.header("X-RateLimit-Remaining", String(decision.remaining));
+  // Unix-epoch seconds — matches the de-facto industry standard (GitHub,
+  // Twitter, AWS) and stays consistent with Retry-After, which is also
+  // seconds. Previously this emitted an ISO-Instant string; proxies and
+  // client libs that parse as integer would silently see NaN.
+  c.header("X-RateLimit-Reset", String(Math.floor(decision.resetAt.epochMilliseconds / 1000)));
+}
+
+function respondRateLimited(c: Context, decision: RateLimitDecision, bucket: string): Response {
+  // Build a RateLimitError so the wire shape is identical to the L3
+  // dispatcher path. serializeError adds i18nKey, requestId, timestamp —
+  // fields a hand-rolled body would silently miss.
+  const err = new RateLimitError({
+    bucket,
+    limit: decision.limit,
+    windowSeconds: decision.windowSeconds,
+    remaining: decision.remaining,
+    retryAfterSeconds: decision.retryAfterSeconds,
+    resetAt: decision.resetAt.toString(),
+  });
+  c.header("Retry-After", String(Math.max(1, decision.retryAfterSeconds)));
+  setRateLimitHeaders(c, decision);
+  const reqId = requestContext.get()?.requestId;
+  return c.json(serializeError(err, reqId), 429);
+}

package/src/rate-limit/resolver.ts

@@ -0,0 +1,267 @@
+import type Redis from "ioredis";
+import { RateLimitError } from "../errors";
+import { RedisKeys } from "../pipeline/redis-keys";
+
+// Token-Bucket rate limiter, atomic via Redis Lua. One round-trip per
+// check — the script computes the bucket state inline and either deducts
+// or rejects.
+//
+// Why Token Bucket: bursts are allowed up to `limit`, refill is steady
+// at `limit / windowSeconds` per second. Sliding window would be more
+// fair but needs more Redis ops; fixed window is simpler but gives 2x
+// burst at boundaries. Token Bucket sits in the right trade-off zone.
+//
+// Storage layout per bucket:
+//   <key> hash with two fields:
+//     tokens  — float, current tokens in the bucket
+//     ts      — last refill timestamp (ms since epoch)
+//   TTL = 2 × windowSeconds (long enough to not lose state across refill,
+//         short enough to clean up dead buckets)
+//
+// The Lua script does: load → refill based on elapsed time → check cost
+// → deduct or reject. Returns [allowed, remaining, resetAfterMs].
+
+// KEYS[1] — bucket key
+// ARGV[1] — limit (max tokens)
+// ARGV[2] — refillRatePerMs (limit / (windowSeconds * 1000))
+// ARGV[3] — cost (tokens to deduct, default 1)
+// ARGV[4] — nowMs (server time, passed in for testability + drift safety)
+// ARGV[5] — ttlSeconds (key TTL)
+//
+// Returns: { allowed (1|0), remainingTokens (int floor), retryAfterMs (int) }
+//
+// The peek script (TOKEN_BUCKET_PEEK_LUA) below is the same logic minus
+// the HMSET — used by ops queries to inspect a bucket without nudging
+// the refill timestamp. Two scripts so neither has to grow a "writeback"
+// flag and a state-machine.
+const TOKEN_BUCKET_LUA = `
+local key = KEYS[1]
+local limit = tonumber(ARGV[1])
+local refillRatePerMs = tonumber(ARGV[2])
+local cost = tonumber(ARGV[3])
+local nowMs = tonumber(ARGV[4])
+local ttl = tonumber(ARGV[5])
+
+local data = redis.call('HMGET', key, 'tokens', 'ts')
+local tokens = tonumber(data[1])
+local ts = tonumber(data[2])
+
+if tokens == nil then
+  tokens = limit
+  ts = nowMs
+else
+  local elapsed = math.max(0, nowMs - ts)
+  tokens = math.min(limit, tokens + elapsed * refillRatePerMs)
+  ts = nowMs
+end
+
+local allowed = 0
+local retryAfterMs = 0
+if tokens >= cost then
+  tokens = tokens - cost
+  allowed = 1
+else
+  -- Time until enough tokens accumulate to satisfy this request.
+  local deficit = cost - tokens
+  retryAfterMs = math.ceil(deficit / refillRatePerMs)
+end
+
+redis.call('HMSET', key, 'tokens', tokens, 'ts', ts)
+redis.call('EXPIRE', key, ttl)
+
+return { allowed, math.floor(tokens), retryAfterMs }
+`;
+
+// Read-only peek. Same refill maths, but writes nothing back — the
+// bucket state at peek time stays identical to the state the next real
+// check() would see. Used by ops/status queries that must not deduct
+// tokens or shift the refill timestamp.
+//
+// KEYS[1] — bucket key
+// ARGV[1] — limit
+// ARGV[2] — refillRatePerMs
+// ARGV[3] — nowMs
+//
+// Returns: { remainingTokens (int floor), retryAfterMs (int — until 1 token available) }
+const TOKEN_BUCKET_PEEK_LUA = `
+local key = KEYS[1]
+local limit = tonumber(ARGV[1])
+local refillRatePerMs = tonumber(ARGV[2])
+local nowMs = tonumber(ARGV[3])
+
+local data = redis.call('HMGET', key, 'tokens', 'ts')
+local tokens = tonumber(data[1])
+local ts = tonumber(data[2])
+
+if tokens == nil then
+  tokens = limit
+else
+  local elapsed = math.max(0, nowMs - ts)
+  tokens = math.min(limit, tokens + elapsed * refillRatePerMs)
+end
+
+local retryAfterMs = 0
+if tokens < 1 then
+  retryAfterMs = math.ceil((1 - tokens) / refillRatePerMs)
+end
+
+return { math.floor(tokens), retryAfterMs }
+`;
+
+export type RateLimitDecision = {
+  readonly allowed: boolean;
+  readonly limit: number;
+  readonly remaining: number;
+  readonly retryAfterSeconds: number;
+  readonly windowSeconds: number;
+  readonly resetAt: Temporal.Instant;
+};
+
+export type RateLimitConfig = {
+  readonly limit: number;
+  readonly windowSeconds: number;
+  readonly cost?: number;
+};
+
+export type RateLimitResolver = {
+  // Atomic check + deduct. Returns the decision and current bucket state
+  // — caller decides whether to throw RateLimitError or proceed.
+  check(bucket: string, config: RateLimitConfig): Promise<RateLimitDecision>;
+
+  // Convenience: throws RateLimitError when blocked. Useful inside the
+  // dispatcher / middleware code-paths where the failure shape is fixed.
+  enforce(bucket: string, config: RateLimitConfig): Promise<RateLimitDecision>;
+
+  // Read-only inspection: returns the same shape as check() but never
+  // mutates the bucket — no token deduction, no refill-timestamp update.
+  // Use for ops/status queries (e.g. "kumiko rl status user:42") that
+  // must observe the bucket without disturbing it.
+  peek(bucket: string, config: Omit<RateLimitConfig, "cost">): Promise<RateLimitDecision>;
+};
+
+export type RateLimitResolverOptions = {
+  readonly redis: Redis;
+  // Override the prefix for tests. Production uses RedisKeys.rateLimit.
+  readonly keyPrefix?: string;
+  // Override the time source for tests. Production uses Date.now().
+  readonly nowMs?: () => number;
+};
+
+type LuaResult = readonly [number, number, number];
+
+// We register the script once per Redis client via defineCommand so each
+// check is a single round-trip with the script already cached on the
+// server (ioredis falls back to LOADing the script if the SHA is
+// missing). Using defineCommand also keeps the call-site idiomatic
+// (`redis.kumikoRateLimit(...)`) instead of building raw protocol calls.
+type CommandClient = Redis & {
+  kumikoRateLimit(
+    key: string,
+    limit: string,
+    refillRatePerMs: string,
+    cost: string,
+    nowMs: string,
+    ttlSeconds: string,
+  ): Promise<LuaResult>;
+  kumikoRateLimitPeek(
+    key: string,
+    limit: string,
+    refillRatePerMs: string,
+    nowMs: string,
+  ): Promise<readonly [number, number]>;
+};
+
+const REGISTERED = new WeakSet<Redis>();
+
+function ensureCommand(redis: Redis): CommandClient {
+  if (!REGISTERED.has(redis)) {
+    redis.defineCommand("kumikoRateLimit", {
+      numberOfKeys: 1,
+      lua: TOKEN_BUCKET_LUA,
+    });
+    redis.defineCommand("kumikoRateLimitPeek", {
+      numberOfKeys: 1,
+      lua: TOKEN_BUCKET_PEEK_LUA,
+    });
+    REGISTERED.add(redis);
+  }
+  return redis as CommandClient;
+}
+
+export function createRateLimitResolver(opts: RateLimitResolverOptions): RateLimitResolver {
+  const client = ensureCommand(opts.redis);
+  const prefix = opts.keyPrefix ?? RedisKeys.rateLimit;
+  const now = opts.nowMs ?? (() => Date.now());
+
+  async function check(bucket: string, config: RateLimitConfig): Promise<RateLimitDecision> {
+    const cost = config.cost ?? 1;
+    const refillRatePerMs = config.limit / (config.windowSeconds * 1000);
+    const ttlSeconds = Math.max(1, config.windowSeconds * 2);
+    const nowMs = now();
+
+    const [allowedFlag, remaining, retryAfterMs] = await client.kumikoRateLimit(
+      `${prefix}${bucket}`,
+      String(config.limit),
+      String(refillRatePerMs),
+      String(cost),
+      String(nowMs),
+      String(ttlSeconds),
+    );
+
+    const retryAfterSeconds = Math.ceil(retryAfterMs / 1000);
+    const resetAt = Temporal.Instant.fromEpochMilliseconds(nowMs + retryAfterMs);
+
+    return {
+      allowed: allowedFlag === 1,
+      limit: config.limit,
+      remaining,
+      retryAfterSeconds,
+      windowSeconds: config.windowSeconds,
+      resetAt,
+    };
+  }
+
+  async function enforce(bucket: string, config: RateLimitConfig): Promise<RateLimitDecision> {
+    const decision = await check(bucket, config);
+    if (decision.allowed) return decision;
+    throw new RateLimitError({
+      bucket,
+      limit: decision.limit,
+      windowSeconds: decision.windowSeconds,
+      remaining: decision.remaining,
+      retryAfterSeconds: decision.retryAfterSeconds,
+      resetAt: decision.resetAt.toString(),
+    });
+  }
+
+  async function peek(
+    bucket: string,
+    config: Omit<RateLimitConfig, "cost">,
+  ): Promise<RateLimitDecision> {
+    const refillRatePerMs = config.limit / (config.windowSeconds * 1000);
+    const nowMs = now();
+
+    const [remaining, retryAfterMs] = await client.kumikoRateLimitPeek(
+      `${prefix}${bucket}`,
+      String(config.limit),
+      String(refillRatePerMs),
+      String(nowMs),
+    );
+
+    const retryAfterSeconds = Math.ceil(retryAfterMs / 1000);
+    const resetAt = Temporal.Instant.fromEpochMilliseconds(nowMs + retryAfterMs);
+
+    return {
+      // peek doesn't deduct, so a "would-be" allowed flag is meaningful:
+      // true iff at least one token is available right now.
+      allowed: remaining >= 1,
+      limit: config.limit,
+      remaining,
+      retryAfterSeconds,
+      windowSeconds: config.windowSeconds,
+      resetAt,
+    };
+  }
+
+  return { check, enforce, peek };
+}