@forgezero/access 0.1.0

package/dist/pipeline.d.ts

@@ -0,0 +1,92 @@
+import { type AccessControl, type RequestContext, type RouteRegistry, type SessionContext } from './index';
+/**
+ * The pipeline every adapter runs.
+ *
+ * Written once, here, because a security order re-implemented per framework is
+ * a security order that will differ per framework. An adapter's whole job is to
+ * translate a request in and a response out; it never decides anything.
+ *
+ * ## Order, and why each step sits where it does
+ *
+ *   1  match          the PATTERN, never the pathname
+ *   2  exists         stage · realm · feature   → 404, never 403
+ *   3  session        policy factors            → 401 / 428
+ *   4  grants         by stem                   → 403
+ *   5  rate           before any work is done   → 429
+ *   6  validate       params · query · body     → 422
+ *   7  before         conditions; a Refusal keeps its status, Settled replays
+ *   8  action         FRESH proof, bound to the record before loaded  → 428
+ *   9  handler        business logic only
+ *  10  response       validated in development
+ *  11  after          queued, never awaited, runs even when 7 threw
+ *
+ * Step 5 precedes validation so a flood of malformed bodies costs a counter
+ * increment rather than a parse. Step 8 follows 7 because binding a proof to a
+ * record requires the record — that is what stops a key minted for order A
+ * authorising order B.
+ */
+export interface Handler {
+    (context: RequestContext, state: Record<string, unknown>): unknown | Promise<unknown>;
+}
+export type HandlerRegistry = Record<string, Handler>;
+/** Handlers bind by route key, exactly one each. */
+export declare function defineHandlers<R extends RouteRegistry>(routes: R, handlers: Partial<Record<Extract<keyof R, string>, Handler>>): HandlerRegistry;
+/** Supplied by the host. The pipeline never learns how a session is stored. */
+export interface SessionResolver {
+    (request: Request): Promise<SessionContext | undefined>;
+}
+export interface RateStore {
+    /** Returns false when the caller is over the limit. */
+    take(key: string, limit: number, windowSeconds: number): Promise<boolean>;
+}
+/** Validates one value against one schema. Satisfied by `@forgezero/runtime/schema`. */
+export interface Validator {
+    validate(schema: unknown, value: unknown): {
+        ok: true;
+        value: unknown;
+    } | {
+        ok: false;
+        errors: readonly {
+            path: string;
+            message: string;
+        }[];
+    };
+}
+/** Mints and consumes one-time step-up keys. Storage is the host's business. */
+export interface StepUpStore {
+    issue(args: {
+        route: string;
+        method: string;
+        target?: string;
+        targetKey?: string;
+        userKey: string;
+        factors: readonly string[];
+        required: number;
+    }): Promise<string>;
+    consume(key: string, args: {
+        route: string;
+        method: string;
+        targetKey?: string;
+    }): Promise<boolean>;
+}
+export interface Telemetry {
+    span<T>(name: string, attributes: Record<string, unknown>, run: () => Promise<T>): Promise<T>;
+    record(attributes: Record<string, unknown>): void;
+}
+export interface PipelineOptions<R extends RouteRegistry> {
+    access: AccessControl<R>;
+    handlers: HandlerRegistry;
+    session?: SessionResolver;
+    rateStore?: RateStore;
+    validator?: Validator;
+    stepUp?: StepUpStore;
+    telemetry?: Telemetry;
+    /** Off in production: re-validating every response is a cost, not a gate. */
+    validateResponses?: boolean;
+    stage?: () => string | undefined;
+    realm?: (request: Request) => string | undefined;
+}
+/** `15m` → 900. Throws rather than guessing, since a wrong window is silent. */
+export declare function windowSeconds(window: string): number;
+export declare function createPipeline<R extends RouteRegistry>(options: PipelineOptions<R>): (request: Request, routeKey: string, params?: Record<string, string>) => Promise<Response>;
+export type Pipeline = ReturnType<typeof createPipeline>;

package/dist/pipeline.js

@@ -0,0 +1,528 @@
+// src/index.ts
+var SCHEMA_VERSION = 1;
+function assertReadable(document, what) {
+  const version = document.version ?? 1;
+  if (version > SCHEMA_VERSION) {
+    throw new AccessError("ACCESS_VERSION_TOO_NEW", `${what} is version ${version}; this build reads ${SCHEMA_VERSION}. Upgrade @forgezero/access.`);
+  }
+}
+
+class AccessError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "AccessError";
+  }
+}
+
+class Refusal extends Error {
+  status;
+  code;
+  details;
+  retryable;
+  refusal = true;
+  constructor(status, code, message, details = {}, retryable = false) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.details = details;
+    this.retryable = retryable;
+    this.name = "Refusal";
+  }
+}
+function isRefusal(error) {
+  return typeof error === "object" && error !== null && error.refusal === true;
+}
+
+class Settled extends Error {
+  value;
+  status;
+  headers;
+  settled = true;
+  constructor(value, status = 200, headers = {}) {
+    super("Already settled.");
+    this.value = value;
+    this.status = status;
+    this.headers = headers;
+    this.name = "Settled";
+  }
+}
+function isSettled(error) {
+  return typeof error === "object" && error !== null && error.settled === true;
+}
+function defineFactors(factors) {
+  for (const [id, factor] of Object.entries(factors)) {
+    if (factor.status === "shipped" && !(factor.tests?.length ?? 0)) {
+      throw new AccessError("FACTOR_UNTESTED", `Factor "${id}" is marked shipped with no tests. A method nobody exercises is a claim.`);
+    }
+  }
+  return factors;
+}
+function page(label, options = {}) {
+  return { kind: "page", label, ...options };
+}
+function action(label, method, options = {}) {
+  return { kind: "action", label, method, ...options };
+}
+function defineRoutes(routes) {
+  for (const [key, route] of Object.entries(routes)) {
+    const isApi = key.startsWith("api/");
+    if (isApi !== (route.kind === "action")) {
+      throw new AccessError("ROUTE_KIND_MISMATCH", `"${key}": routes under api/ must be actions, and actions must be under api/.`);
+    }
+    if (route.kind === "action" && route.page && !(route.page in routes)) {
+      throw new AccessError("ROUTE_DANGLING_PAGE", `"${key}" names page "${route.page}", which does not exist.`);
+    }
+    if (route.kind === "action" && route.response) {
+      for (const status of Object.keys(route.response)) {
+        if (!route.response[Number(status)]) {
+          throw new AccessError("ROUTE_EMPTY_RESPONSE", `"${key}" declares status ${status} with no schema.`);
+        }
+      }
+    }
+  }
+  return routes;
+}
+function codePolicy(config) {
+  return {
+    roles: async () => config.roles,
+    enabledFactors: async () => config.enabledFactors
+  };
+}
+function externalPolicy(reader) {
+  return {
+    async roles() {
+      const roles = await reader.roles();
+      for (const role of roles)
+        assertReadable(role, `role "${role.roleKey}"`);
+      return roles;
+    },
+    enabledFactors: () => reader.enabledFactors()
+  };
+}
+function stemOf(routeKey, strip) {
+  const withoutApi = routeKey.startsWith("api/") ? routeKey.slice(4) : routeKey;
+  return strip ? withoutApi.replace(strip, "") : withoutApi;
+}
+function grantsRoute(grants, routeKey, options = {}) {
+  const { mode = "inherit", sharesGrantWith, strip } = options;
+  const stem = stemOf(routeKey, strip);
+  const shared = sharesGrantWith ? stemOf(sharesGrantWith, strip) : undefined;
+  return grants.some((grant) => {
+    const granted = stemOf(grant, strip);
+    if (stem === granted || granted === routeKey)
+      return true;
+    if (shared !== undefined && (granted === shared || granted === sharesGrantWith))
+      return true;
+    return mode === "inherit" && stem.startsWith(granted + "/");
+  });
+}
+function fulfilledActionFactors() {
+  return [];
+}
+function defineAccessControl(config) {
+  assertReadable(config, "access control");
+  const routeKeys = new Set(Object.keys(config.routes));
+  const actionKeys = Object.entries(config.routes).filter(([, route]) => route.kind === "action").map(([key]) => key);
+  const checkKeys = (listName, name, keys) => {
+    if (keys.length === 0) {
+      throw new AccessError("POLICY_ORPHANED", `${listName} "${name}" binds no routes.`);
+    }
+    for (const key of keys) {
+      if (!routeKeys.has(key)) {
+        throw new AccessError("POLICY_UNKNOWN_ROUTE", `${listName} "${name}" names "${key}", which is not a route.`);
+      }
+    }
+  };
+  const sessionOf = new Map;
+  for (const [name, policy] of Object.entries(config.sessionPolicies)) {
+    checkKeys("Session policy", name, policy.routes);
+    for (const key of policy.routes) {
+      if (sessionOf.has(key)) {
+        throw new AccessError("SESSION_DUPLICATE", `"${key}" is in more than one session policy.`);
+      }
+      sessionOf.set(key, policy);
+    }
+    for (const factor of policy.factors) {
+      const spec = config.factors[factor];
+      if (!spec)
+        throw new AccessError("FACTOR_UNKNOWN", `Session policy "${name}" names unknown factor "${factor}".`);
+      if (spec.kind === "action") {
+        throw new AccessError("FACTOR_WRONG_KIND", `"${factor}" is action-only and cannot establish a session.`);
+      }
+    }
+  }
+  const unclassified = [...routeKeys].filter((key) => !sessionOf.has(key));
+  if (unclassified.length > 0) {
+    throw new AccessError("SESSION_INCOMPLETE", `No session policy covers: ${unclassified.join(", ")}. Every route needs exactly one.`);
+  }
+  const actionOf = new Map;
+  for (const [name, policy] of Object.entries(config.actionPolicies ?? {})) {
+    checkKeys("Action policy", name, policy.routes);
+    if (policy.required < 1 || policy.required > policy.factors.length) {
+      throw new AccessError("ACTION_UNSATISFIABLE", `Action policy "${name}" requires ${policy.required} of ${policy.factors.length} factors.`);
+    }
+    for (const factor of policy.factors) {
+      const spec = config.factors[factor];
+      if (!spec)
+        throw new AccessError("FACTOR_UNKNOWN", `Action policy "${name}" names unknown factor "${factor}".`);
+      if (spec.kind === "session") {
+        throw new AccessError("FACTOR_WRONG_KIND", `"${factor}" is session-only and cannot authorise an action.`);
+      }
+    }
+    for (const key of policy.routes) {
+      if (actionOf.has(key)) {
+        throw new AccessError("ACTION_DUPLICATE", `"${key}" is in more than one action policy.`);
+      }
+      actionOf.set(key, policy);
+    }
+  }
+  const rateOf = new Map;
+  const rateLists = Object.entries(config.ratePolicies ?? {});
+  for (const [name, policy] of rateLists) {
+    checkKeys("Rate policy", name, policy.routes);
+    for (const key of policy.routes) {
+      if (rateOf.has(key)) {
+        throw new AccessError("RATE_DUPLICATE", `"${key}" is in more than one rate policy.`);
+      }
+      rateOf.set(key, policy);
+    }
+  }
+  if (rateLists.length > 0) {
+    const unrated = actionKeys.filter((key) => !rateOf.has(key));
+    if (unrated.length > 0) {
+      throw new AccessError("RATE_INCOMPLETE", `No rate policy covers: ${unrated.join(", ")}. Declaring any means declaring all.`);
+    }
+  }
+  const beforeOf = new Map;
+  for (const [name, handler] of Object.entries(config.beforeHandlers ?? {})) {
+    checkKeys("Before handler", name, handler.routes);
+    for (const key of handler.routes) {
+      beforeOf.set(key, [...beforeOf.get(key) ?? [], handler]);
+    }
+  }
+  const afterOf = new Map;
+  for (const [name, handler] of Object.entries(config.afterHandlers ?? {})) {
+    checkKeys("After handler", name, handler.routes);
+    for (const key of handler.routes) {
+      afterOf.set(key, [...afterOf.get(key) ?? [], handler]);
+    }
+  }
+  const features = config.features ?? [];
+  return {
+    version: config.version ?? SCHEMA_VERSION,
+    routes: config.routes,
+    features,
+    source: config.source,
+    keys: () => Object.keys(config.routes),
+    get: (key) => config.routes[key],
+    exists(key, context) {
+      const route = config.routes[key];
+      if (!route)
+        return false;
+      if (route.feature && !features.includes(route.feature))
+        return false;
+      if (context?.stage && route.stages && !route.stages.includes(context.stage))
+        return false;
+      if (context?.realm && route.realms && !route.realms.includes(context.realm))
+        return false;
+      return true;
+    },
+    sessionPolicyFor: (key) => sessionOf.get(key),
+    actionPolicyFor: (key) => actionOf.get(key),
+    ratePolicyFor: (key) => rateOf.get(key),
+    beforeFor: (key) => beforeOf.get(key) ?? [],
+    afterFor: (key) => afterOf.get(key) ?? []
+  };
+}
+function authorise(args) {
+  const { access, routeKey, stage, realm, session, roles } = args;
+  if (!access.exists(routeKey, { stage, realm })) {
+    return { allow: false, status: 404, code: "NOT_FOUND" };
+  }
+  const policy = access.sessionPolicyFor(routeKey);
+  if (!policy || policy.factors.length === 0)
+    return { allow: true };
+  if (!session)
+    return { allow: false, status: 401, code: "AUTH_REQUIRED" };
+  const missing = policy.factors.filter((factor) => !session.factors.includes(factor));
+  if (missing.length > 0) {
+    return { allow: false, status: 428, code: "SECURITY_REQUIRED", missing };
+  }
+  const grants = roles.filter((role) => session.roleKeys.includes(role.roleKey)).flatMap((role) => role.grants);
+  if (!grantsRoute(grants, routeKey)) {
+    return { allow: false, status: 403, code: "ACCESS_DENIED" };
+  }
+  return { allow: true };
+}
+function resolveActionFactors(policy, enabled) {
+  const available = policy.factors.filter((factor) => enabled.includes(factor));
+  return { available, required: policy.required, satisfiable: available.length >= policy.required };
+}
+function impactOfDisabling(access, enabledAfter) {
+  const broken = [];
+  for (const key of access.keys()) {
+    const policy = access.actionPolicyFor(key);
+    if (!policy)
+      continue;
+    const { available, required, satisfiable } = resolveActionFactors(policy, enabledAfter);
+    if (!satisfiable)
+      broken.push({ route: key, available: available.length, required });
+  }
+  return broken;
+}
+var VERSION = "0.1.0";
+
+// src/pipeline.ts
+function defineHandlers(routes, handlers) {
+  for (const key of Object.keys(handlers)) {
+    if (!(key in routes)) {
+      throw new AccessError("HANDLER_UNKNOWN_ROUTE", `Handler "${key}" is not a route.`);
+    }
+    if (routes[key].kind !== "action") {
+      throw new AccessError("HANDLER_ON_PAGE", `"${key}" is a page; only actions take handlers.`);
+    }
+  }
+  return handlers;
+}
+var WINDOWS = { s: 1, m: 60, h: 3600, d: 86400 };
+function windowSeconds(window) {
+  const match = /^(\d+)([smhd])$/.exec(window);
+  if (!match)
+    throw new AccessError("RATE_WINDOW_INVALID", `"${window}" is not a window like 30s, 1m, 15m, 1h, 1d.`);
+  return Number(match[1]) * WINDOWS[match[2]];
+}
+var problem = (status, code, message, extra = {}) => new Response(JSON.stringify({ ok: false, error: { code, message }, ...extra }), {
+  status,
+  headers: { "content-type": "application/json" }
+});
+var outcomeResponse = (outcome) => {
+  const headers = { "content-type": "application/json" };
+  if (outcome.status === 428) {
+    headers["x-security-mode"] = "session";
+    if (outcome.missing)
+      headers["x-security-required"] = outcome.missing.join(",");
+  }
+  return new Response(JSON.stringify({
+    ok: false,
+    error: { code: outcome.code, message: refusalMessage(outcome.status) },
+    ...outcome.missing ? { missing: outcome.missing } : {}
+  }), { status: outcome.status, headers });
+};
+function refusalMessage(status) {
+  switch (status) {
+    case 404:
+      return "Not found.";
+    case 401:
+      return "Sign in to continue.";
+    case 403:
+      return "Your role cannot perform this action.";
+    case 428:
+      return "Complete the required security check to continue.";
+    case 429:
+      return "Too many requests. Try again shortly.";
+    default:
+      return "Refused.";
+  }
+}
+function createPipeline(options) {
+  const {
+    access,
+    handlers,
+    session: resolveSession,
+    rateStore,
+    validator,
+    stepUp,
+    telemetry,
+    validateResponses = false
+  } = options;
+  return async function run(request, routeKey, params = {}) {
+    const url = new URL(request.url);
+    const stage = options.stage?.();
+    const realm = options.realm?.(request);
+    const record = (attributes) => telemetry?.record(attributes);
+    record({ "access.route": routeKey, "access.realm": realm, "access.stage": stage });
+    if (!access.exists(routeKey, { stage, realm })) {
+      record({ "access.outcome": "denied", "access.status": 404, "access.reason": "not_found" });
+      return problem(404, "NOT_FOUND", "Not found.");
+    }
+    const route = access.get(routeKey);
+    const session = await resolveSession?.(request);
+    const roles = await access.source?.roles() ?? [];
+    const outcome = authorise({ access, routeKey, stage, realm, session, roles });
+    if (!outcome.allow) {
+      record({
+        "access.outcome": "denied",
+        "access.status": outcome.status,
+        "access.reason": outcome.code,
+        "access.policy": outcome.policy
+      });
+      return outcomeResponse(outcome);
+    }
+    const rate = access.ratePolicyFor(routeKey);
+    if (rate && rateStore) {
+      const subject = rate.by === "session" ? session?.userKey ?? "anon" : rate.by === "realm" ? realm ?? "none" : rate.by === "apiKey" ? request.headers.get("x-api-key") ?? "none" : request.headers.get("x-forwarded-for") ?? "unknown";
+      const allowed = await rateStore.take(`${routeKey}:${rate.by}:${subject}`, rate.limit, windowSeconds(rate.window));
+      if (!allowed) {
+        record({ "access.outcome": "denied", "access.status": 429, "access.reason": "rate_limited" });
+        return problem(429, "RATE_LIMITED", refusalMessage(429));
+      }
+    }
+    let body;
+    const query = Object.fromEntries(url.searchParams);
+    if (validator) {
+      const checks = [];
+      if (route.params)
+        checks.push(["params", route.params, params]);
+      if (route.query)
+        checks.push(["query", route.query, query]);
+      if (route.headers)
+        checks.push(["headers", route.headers, Object.fromEntries(request.headers)]);
+      if (route.body) {
+        body = await request.json().catch(() => {
+          return;
+        });
+        checks.push(["body", route.body, body]);
+      }
+      for (const [where, schema, value] of checks) {
+        const result2 = validator.validate(schema, value);
+        if (!result2.ok) {
+          record({ "access.outcome": "denied", "access.status": 422, "access.reason": `invalid_${where}` });
+          return problem(422, "INVALID_REQUEST", `The ${where} did not match what this route accepts.`, {
+            errors: result2.errors
+          });
+        }
+        if (where === "body")
+          body = result2.value;
+      }
+    } else if (route.body) {
+      body = await request.json().catch(() => {
+        return;
+      });
+    }
+    const context = {
+      route: routeKey,
+      method: route.method,
+      url,
+      params,
+      query,
+      body,
+      headers: request.headers,
+      session,
+      realm,
+      stage,
+      ok: (value) => new Response(JSON.stringify(value), { headers: { "content-type": "application/json" } })
+    };
+    const state = {};
+    const completed = [];
+    const before = access.beforeFor(routeKey);
+    let failure;
+    for (let index = 0;index < before.length; index += 1) {
+      try {
+        Object.assign(state, await before[index].run(context, state) ?? {});
+        completed.push(index);
+      } catch (error) {
+        failure = error;
+        break;
+      }
+    }
+    const runAfter = (result2) => {
+      queueMicrotask(() => {
+        for (const handler2 of [...access.afterFor(routeKey)].reverse()) {
+          try {
+            handler2.run(context, result2, state);
+          } catch {}
+        }
+      });
+    };
+    if (failure) {
+      runAfter(failure);
+      if (isSettled(failure)) {
+        record({ "access.outcome": "settled", "access.status": failure.status });
+        return failure.value instanceof Response ? failure.value : new Response(failure.status === 204 ? null : JSON.stringify(failure.value), {
+          status: failure.status,
+          headers: { "content-type": "application/json", ...failure.headers }
+        });
+      }
+      if (isRefusal(failure)) {
+        record({
+          "access.outcome": "denied",
+          "access.status": failure.status,
+          "access.reason": failure.code
+        });
+        return problem(failure.status, failure.code, failure.message, {
+          ...failure.details,
+          ...failure.retryable ? { retryable: true } : {}
+        });
+      }
+      record({ "access.outcome": "error", "access.reason": "before_threw" });
+      return problem(500, "INTERNAL", "The request could not be completed.");
+    }
+    const actionPolicy = access.actionPolicyFor(routeKey);
+    if (actionPolicy && session) {
+      const enabled = await access.source?.enabledFactors() ?? actionPolicy.factors;
+      const { satisfiable, available } = resolveActionFactors(actionPolicy, enabled);
+      if (!satisfiable) {
+        record({ "access.outcome": "denied", "access.status": 403, "access.reason": "factors_unavailable" });
+        return problem(403, "FACTORS_UNAVAILABLE", "A required security method is not enabled on this account.");
+      }
+      const presented = request.headers.get("x-security-request-key");
+      const targetKey = typeof body?.id === "string" ? body.id : undefined;
+      const consumed = presented && stepUp ? await stepUp.consume(presented, { route: routeKey, method: route.method, targetKey }) : false;
+      if (!consumed) {
+        const key = stepUp ? await stepUp.issue({
+          route: routeKey,
+          method: route.method,
+          target: actionPolicy.target,
+          targetKey,
+          userKey: session.userKey,
+          factors: available,
+          required: actionPolicy.required
+        }) : "";
+        record({ "access.outcome": "denied", "access.status": 428, "access.reason": "step_up_required" });
+        return new Response(JSON.stringify({
+          ok: false,
+          error: { code: "SECURITY_REQUIRED", message: refusalMessage(428) },
+          security: {
+            scope: "action",
+            route: routeKey,
+            factors: available,
+            required: actionPolicy.required,
+            satisfied: fulfilledActionFactors()
+          }
+        }), {
+          status: 428,
+          headers: {
+            "content-type": "application/json",
+            "x-security-mode": "action",
+            "x-security-request-key": key,
+            "x-security-required": available.join(",")
+          }
+        });
+      }
+    }
+    const handler = handlers[routeKey];
+    if (!handler) {
+      return problem(501, "NOT_IMPLEMENTED", "This route has no handler.");
+    }
+    const result = await (telemetry ? telemetry.span("handler", { "access.route": routeKey }, async () => handler(context, state)) : handler(context, state));
+    if (validateResponses && validator && route.response) {
+      const schema = route.response[200];
+      if (schema && !(result instanceof Response)) {
+        const check = validator.validate(schema, result);
+        if (!check.ok) {
+          throw new AccessError("RESPONSE_MISMATCH", `"${routeKey}" returned a shape it does not declare: ${check.errors[0]?.message}`);
+        }
+      }
+    }
+    runAfter(result);
+    record({ "access.outcome": "allowed", "access.status": 200 });
+    return result instanceof Response ? result : new Response(JSON.stringify(result), { headers: { "content-type": "application/json" } });
+  };
+}
+export {
+  windowSeconds,
+  defineHandlers,
+  createPipeline
+};

package/dist/rate-limit.d.ts

@@ -0,0 +1,54 @@
+import type { RateStore } from './pipeline';
+/**
+ * Rate limit stores.
+ *
+ * The pipeline declares `RateStore` and never implements one, so a project on
+ * Redis, Durable Objects or a single process all satisfy the same interface.
+ *
+ * Every store here is a FIXED WINDOW, which is the honest simple choice: it
+ * permits up to 2× the limit across a window boundary. Sliding windows avoid
+ * that and cost either a sorted set per subject or arithmetic on two counters.
+ * For "10 sign-ins per 15 minutes" the burst is irrelevant; for a payment API it
+ * is not, and that is when to reach for `slidingWindowStore`.
+ */
+/**
+ * Single process, no dependencies. Correct for one node and for tests, wrong
+ * the moment there are two — each replica keeps its own count, so N replicas
+ * permit N× the limit.
+ */
+export declare function memoryStore(): RateStore & {
+    reset(): void;
+    size(): number;
+};
+/** Just enough of a Redis client to count, so this file imports nothing. */
+export interface RedisLike {
+    incr(key: string): Promise<number>;
+    expire(key: string, seconds: number): Promise<unknown>;
+}
+/**
+ * Redis fixed window.
+ *
+ * `INCR` then `EXPIRE` only when the counter is 1. Setting the TTL on every
+ * increment slides the window forward on each request, so a steady stream of
+ * traffic keeps the key alive forever and the limit never resets — a bug that
+ * looks like the limiter working perfectly right up until nobody can call
+ * anything.
+ */
+export declare function redisStore(redis: RedisLike, prefix?: string): RateStore;
+/** Cloudflare Durable Object, or anything with the same get/put shape. */
+export interface DurableStorageLike {
+    get<T>(key: string): Promise<T | undefined>;
+    put<T>(key: string, value: T): Promise<void>;
+}
+export declare function durableObjectStore(storage: DurableStorageLike, prefix?: string): RateStore;
+/**
+ * Sliding window, approximated from two fixed windows.
+ *
+ * Weights the previous window by how much of it still overlaps, which removes
+ * the 2× boundary burst without keeping a timestamp per request. Costs two
+ * counters per subject instead of one — worth it where a burst actually matters
+ * and not worth it where it does not.
+ */
+export declare function slidingWindowStore(base: RateStore & {
+    peek?: never;
+}): RateStore;