@vc1023/passkey-2fa 0.1.0 → 0.2.0

package/README.md

@@ -113,7 +113,36 @@ import {
 // each ceremony returns { ok:true } | { ok:false, reason:"cancelled"|"unsupported"|"error" }
 ```
 
+## Distributed rate limiting (optional)
+
+The default limiter is in-memory and **per-instance** (fine for one instance; not shared across serverless instances/regions). For multi-instance production, inject a distributed `RateLimiter` — e.g. Upstash Redis:
+
+```ts
+// app/lib/auth.ts
+import { Ratelimit } from "@upstash/ratelimit";
+import { Redis } from "@upstash/redis";
+import { createPasskeyAuthHandlers, type RateLimiter } from "@vc1023/passkey-2fa/routes";
+
+const redis = Redis.fromEnv(); // UPSTASH_REDIS_REST_URL + UPSTASH_REDIS_REST_TOKEN
+const cache = new Map<string, Ratelimit>();
+
+const rateLimit: RateLimiter = async (key, limit, windowMs) => {
+  const id = `${limit}:${windowMs}`;
+  let rl = cache.get(id);
+  if (!rl) {
+    rl = new Ratelimit({ redis, limiter: Ratelimit.slidingWindow(limit, `${windowMs} ms`), prefix: "pk2fa" });
+    cache.set(id, rl);
+  }
+  const r = await rl.limit(key);
+  return { ok: r.success, retryAfterSeconds: Math.max(0, Math.ceil((r.reset - Date.now()) / 1000)) };
+};
+
+export const handlers = createPasskeyAuthHandlers({ rateLimit /*, onEvent */ });
+```
+
+`RateLimiter` is `(key, limit, windowMs) => RateLimitResult | Promise<RateLimitResult>` — the per-endpoint limit/window are passed in, so one implementation serves every route.
+
 ## Notes
 - Route handlers run on `runtime = "nodejs"` (the AAL2 token uses `node:crypto`). The middleware is Edge-safe.
-- Rate limiting is in-memory / per-instance — back it with Upstash/Firewall at scale.
+- The AAL2 session is **bound to the Supabase session id** (fail-closed): a stolen AAL2 cookie can't elevate a different session.
 - Server validation is enforced; you may also `signUpSchema.safeParse()` client-side for instant feedback.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vc1023/passkey-2fa",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Drop-in password + passkey (WebAuthn) 2FA for Next.js App Router + Supabase.",
   "license": "MIT",
   "private": false,
@@ -18,7 +18,7 @@
     "./migrations/*": "./migrations/*"
   },
   "bin": {
-    "passkey-2fa": "./bin/check-env.mjs"
+    "passkey-2fa": "bin/check-env.mjs"
   },
   "files": [
     "src",

package/src/guard.ts

@@ -41,10 +41,13 @@ export async function getAal2UserId(): Promise<string | null> {
   const store = await cookies();
   const claims = verifyAal2Token(store.get(AAL2_COOKIE)?.value, mfaSecret());
   if (!claims || claims.sub !== user.id) return null;
-  if (claims.sid) {
-    const sid = await currentSessionId();
-    if (sid && claims.sid !== sid) return null;
-  }
+  // Session binding is REQUIRED (fail-closed): the AAL2 token must carry a `sid`
+  // and it must match the live Supabase session. A stolen AAL2 cookie therefore
+  // can't elevate a different session, and a token minted without a binding is
+  // rejected. Supabase access tokens always carry `session_id`, so this does not
+  // lock out legitimate sessions.
+  const sid = await currentSessionId();
+  if (!claims.sid || !sid || claims.sid !== sid) return null;
   return user.id;
 }
 

package/src/rate-limit.test.ts

@@ -1,11 +1,11 @@
 import { describe, expect, it } from "vitest";
-import { rateLimit } from "./rate-limit";
+import { inMemoryRateLimit } from "./rate-limit";
 
-describe("rateLimit", () => {
+describe("inMemoryRateLimit", () => {
   it("allows up to the limit then blocks within the window", () => {
     const key = `test-${Math.floor(Math.random() * 1e9)}`;
-    for (let i = 0; i < 3; i++) expect(rateLimit(key, 3, 60_000).ok).toBe(true);
-    const blocked = rateLimit(key, 3, 60_000);
+    for (let i = 0; i < 3; i++) expect(inMemoryRateLimit(key, 3, 60_000)).toMatchObject({ ok: true });
+    const blocked = inMemoryRateLimit(key, 3, 60_000) as { ok: boolean; retryAfterSeconds: number };
     expect(blocked.ok).toBe(false);
     expect(blocked.retryAfterSeconds).toBeGreaterThan(0);
   });
@@ -13,8 +13,8 @@ describe("rateLimit", () => {
   it("uses independent buckets per key", () => {
     const a = `a-${Math.floor(Math.random() * 1e9)}`;
     const b = `b-${Math.floor(Math.random() * 1e9)}`;
-    expect(rateLimit(a, 1, 60_000).ok).toBe(true);
-    expect(rateLimit(a, 1, 60_000).ok).toBe(false);
-    expect(rateLimit(b, 1, 60_000).ok).toBe(true); // different key still allowed
+    expect(inMemoryRateLimit(a, 1, 60_000)).toMatchObject({ ok: true });
+    expect(inMemoryRateLimit(a, 1, 60_000)).toMatchObject({ ok: false });
+    expect(inMemoryRateLimit(b, 1, 60_000)).toMatchObject({ ok: true }); // different key still allowed
   });
 });

package/src/rate-limit.ts

@@ -1,10 +1,24 @@
-// Lightweight in-memory sliding-window rate limiter for the sensitive auth
-// routes.
+// Rate limiting for the sensitive auth routes.
 //
-// SCOPE LIMIT (documented, not hidden): this is PER-INSTANCE. On serverless /
-// Fluid Compute it protects within a warm instance but is NOT distributed across
-// instances/regions. For production at scale, back it with Upstash Redis or a
-// platform firewall (the call sites are the integration points).
+// The limiter is PLUGGABLE: `createPasskeyAuthHandlers` accepts a `rateLimit`
+// (RateLimiter). The default is the in-memory sliding window below — fine for a
+// single instance, but PER-INSTANCE: on serverless / Fluid Compute it protects
+// within a warm instance, NOT across instances/regions. For production at scale,
+// inject a distributed limiter (e.g. Upstash Redis) — see the README. Because
+// RateLimiter may be async, all call sites await it.
+
+export interface RateLimitResult {
+  ok: boolean;
+  retryAfterSeconds: number;
+}
+
+/** A rate limiter. Receives the bucket key + the per-call-site limit/window so a
+ *  single implementation (memory, Redis, …) can serve every endpoint. */
+export type RateLimiter = (
+  key: string,
+  limit: number,
+  windowMs: number,
+) => RateLimitResult | Promise<RateLimitResult>;
 
 interface Bucket {
   count: number;
@@ -13,12 +27,8 @@ interface Bucket {
 
 const buckets = new Map<string, Bucket>();
 
-export interface RateLimitResult {
-  ok: boolean;
-  retryAfterSeconds: number;
-}
-
-export function rateLimit(key: string, limit: number, windowMs: number): RateLimitResult {
+/** Default per-instance in-memory sliding-window limiter. */
+export const inMemoryRateLimit: RateLimiter = (key, limit, windowMs) => {
   const now = Date.now();
   const b = buckets.get(key);
   if (!b || b.resetAt <= now) {
@@ -30,10 +40,11 @@ export function rateLimit(key: string, limit: number, windowMs: number): RateLim
   }
   b.count += 1;
   return { ok: true, retryAfterSeconds: 0 };
-}
+};
 
-/** Best-effort client IP from proxy headers (Vercel sets x-forwarded-for).
- *  Trust only behind a trusted proxy — the header is spoofable otherwise. */
+/** Best-effort client IP from proxy headers. SECURITY: `x-forwarded-for` is only
+ *  trustworthy behind a trusted proxy (e.g. Vercel sets it) — it is client-
+ *  spoofable otherwise, so don't rely on it for anything but coarse throttling. */
 export function clientIp(req: Request): string {
   const xff = req.headers.get("x-forwarded-for");
   return xff?.split(",")[0]?.trim() || req.headers.get("x-real-ip") || "unknown";

package/src/routes.ts

@@ -12,7 +12,7 @@ import {
   verifyAuthentication,
   verifyRegistration,
 } from "./webauthn";
-import { clientIp, rateLimit, tooManyRequests } from "./rate-limit";
+import { clientIp, inMemoryRateLimit, tooManyRequests, type RateLimiter } from "./rate-limit";
 import type { OnAuthEvent } from "./events";
 
 export type { AuthEvent, OnAuthEvent } from "./events";
@@ -27,6 +27,10 @@ function json(data: unknown, status = 200): Response {
 export interface PasskeyAuthOptions {
   /** Hook for audit/analytics/funnel. Errors here are swallowed (best-effort). */
   onEvent?: OnAuthEvent;
+  /** Rate limiter for the credential + ceremony routes. Defaults to a
+   *  per-instance in-memory limiter; inject a distributed one (e.g. Upstash
+   *  Redis) for multi-instance production — see the README. */
+  rateLimit?: RateLimiter;
 }
 
 export interface PasskeyAuthHandlers {
@@ -40,6 +44,7 @@ export interface PasskeyAuthHandlers {
 }
 
 export function createPasskeyAuthHandlers(opts: PasskeyAuthOptions = {}): PasskeyAuthHandlers {
+  const limiter: RateLimiter = opts.rateLimit ?? inMemoryRateLimit;
   const emit: OnAuthEvent = async (e) => {
     try {
       await opts.onEvent?.(e);
@@ -50,7 +55,7 @@ export function createPasskeyAuthHandlers(opts: PasskeyAuthOptions = {}): Passke
 
   return {
     async signUp(req) {
-      const limit = rateLimit(`signup:${clientIp(req)}`, 5, 10 * 60 * 1000);
+      const limit = await limiter(`signup:${clientIp(req)}`, 5, 10 * 60 * 1000);
       if (!limit.ok) return tooManyRequests(limit.retryAfterSeconds);
 
       let body: unknown;
@@ -81,7 +86,7 @@ export function createPasskeyAuthHandlers(opts: PasskeyAuthOptions = {}): Passke
     },
 
     async signIn(req) {
-      const limit = rateLimit(`signin:${clientIp(req)}`, 10, 5 * 60 * 1000);
+      const limit = await limiter(`signin:${clientIp(req)}`, 10, 5 * 60 * 1000);
       if (!limit.ok) return tooManyRequests(limit.retryAfterSeconds);
 
       let body: unknown;
@@ -133,7 +138,7 @@ export function createPasskeyAuthHandlers(opts: PasskeyAuthOptions = {}): Passke
     async registerVerify(req) {
       const user = await getSessionUser();
       if (!user) return json({ ok: false, error: "server" }, 401);
-      const limit = rateLimit(`mfa-reg:${user.id}`, 10, 5 * 60 * 1000);
+      const limit = await limiter(`mfa-reg:${user.id}`, 10, 5 * 60 * 1000);
       if (!limit.ok) return tooManyRequests(limit.retryAfterSeconds);
 
       let response: RegistrationResponseJSON;
@@ -160,7 +165,7 @@ export function createPasskeyAuthHandlers(opts: PasskeyAuthOptions = {}): Passke
     async authenticateVerify(req) {
       const user = await getSessionUser();
       if (!user) return json({ ok: false, error: "server" }, 401);
-      const limit = rateLimit(`mfa-auth:${user.id}`, 10, 5 * 60 * 1000);
+      const limit = await limiter(`mfa-auth:${user.id}`, 10, 5 * 60 * 1000);
       if (!limit.ok) return tooManyRequests(limit.retryAfterSeconds);
 
       let response: AuthenticationResponseJSON;