@vc1023/passkey-2fa 0.1.0

package/src/guard.ts

@@ -0,0 +1,75 @@
+// Server-side AAL2 enforcement. Used by protected Server Components + the route
+// handlers. Runs in the Node runtime (node:crypto via ./aal2).
+
+import { cookies } from "next/headers";
+import { redirect } from "next/navigation";
+import { AAL2_COOKIE, AAL2_TTL_SECONDS, signAal2Token, verifyAal2Token } from "./aal2";
+import { mfaSecret } from "./config";
+import { createServerSupabase } from "./supabase";
+
+/** The current AAL1 (email+password) user, or null. */
+export async function getSessionUser() {
+  const supabase = await createServerSupabase();
+  const {
+    data: { user },
+  } = await supabase.auth.getUser();
+  return user;
+}
+
+/** The current Supabase session id (from the access-token `session_id` claim),
+ *  or null. Stable across token refresh within a session. */
+async function currentSessionId(): Promise<string | null> {
+  const supabase = await createServerSupabase();
+  const {
+    data: { session },
+  } = await supabase.auth.getSession();
+  const token = session?.access_token;
+  if (!token) return null;
+  try {
+    const payload = JSON.parse(Buffer.from(token.split(".")[1], "base64url").toString());
+    return typeof payload.session_id === "string" ? payload.session_id : null;
+  } catch {
+    return null;
+  }
+}
+
+/** User id IFF the session has AAL1 (Supabase) AND a valid AAL2 token whose
+ *  `sub` matches the user AND whose bound `sid` matches the live session. */
+export async function getAal2UserId(): Promise<string | null> {
+  const user = await getSessionUser();
+  if (!user) return 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;
+  }
+  return user.id;
+}
+
+/** Redirect to `signInPath` unless the session is fully AAL2. Returns the user id. */
+export async function requireAal2(signInPath = "/sign-in"): Promise<string> {
+  const id = await getAal2UserId();
+  if (!id) redirect(signInPath);
+  return id;
+}
+
+/** Mint the AAL2 marker after a verified passkey ceremony, bound to the live
+ *  Supabase session. Route-handler only. */
+export async function setAal2Cookie(userId: string): Promise<void> {
+  const sid = await currentSessionId();
+  const store = await cookies();
+  store.set(AAL2_COOKIE, signAal2Token(userId, sid, mfaSecret()), {
+    httpOnly: true,
+    secure: process.env.NODE_ENV === "production",
+    sameSite: "strict",
+    path: "/",
+    maxAge: AAL2_TTL_SECONDS,
+  });
+}
+
+export async function clearAal2Cookie(): Promise<void> {
+  const store = await cookies();
+  store.delete(AAL2_COOKIE);
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+// @vc1023/passkey-2fa — server entry (Node runtime).
+//
+// Drop-in password + passkey (WebAuthn) 2FA for Next.js App Router + Supabase.
+//   - server toolkit:        import { requireAal2, ... } from "@vc1023/passkey-2fa"
+//   - route handlers:        import { createPasskeyAuthHandlers } from "@vc1023/passkey-2fa/routes"
+//   - middleware:            import { createPasskeyMiddleware } from "@vc1023/passkey-2fa/middleware"
+//   - browser helpers:       import { signUp, enrollPasskey, ... } from "@vc1023/passkey-2fa/client"
+//
+// This barrel uses node:crypto + next/headers — server-only. Import client code
+// from "/client".
+
+export * from "./config";
+export * from "./aal2";
+export * from "./validation";
+export * from "./guard";
+export * from "./webauthn";
+export * from "./rate-limit";
+export * from "./supabase";
+export * from "./types";
+export * from "./events";

package/src/middleware.ts

@@ -0,0 +1,55 @@
+// Edge-safe Next.js middleware factory. Refreshes the Supabase (AAL1) session
+// cookies so sessions survive reload + restart, and does a coarse redirect for
+// unauthenticated hits on protected paths. The full AAL2 (second-factor) gate
+// runs server-side in the protected page via `requireAal2()` — it needs
+// node:crypto, unavailable in the Edge runtime, so it is NOT done here.
+//
+// IMPORTANT: only imports `@supabase/ssr` + `./env` (both Edge-safe). Do not add
+// imports that pull in node:crypto.
+
+import { createServerClient, type CookieOptions } from "@supabase/ssr";
+import { NextResponse, type NextRequest } from "next/server";
+import { SUPABASE_ANON_KEY, SUPABASE_URL } from "./env";
+
+export interface PasskeyMiddlewareOptions {
+  /** Path prefixes that require an authenticated (AAL1) session. */
+  protectedPaths: string[];
+  /** Where to send unauthenticated users. Default `/sign-in`. */
+  signInPath?: string;
+}
+
+export function createPasskeyMiddleware(opts: PasskeyMiddlewareOptions) {
+  const signInPath = opts.signInPath ?? "/sign-in";
+
+  return async function middleware(req: NextRequest) {
+    let res = NextResponse.next({ request: req });
+
+    const supabase = createServerClient(SUPABASE_URL(), SUPABASE_ANON_KEY(), {
+      cookies: {
+        getAll() {
+          return req.cookies.getAll();
+        },
+        setAll(cookiesToSet: { name: string; value: string; options: CookieOptions }[]) {
+          for (const { name, value } of cookiesToSet) req.cookies.set(name, value);
+          res = NextResponse.next({ request: req });
+          for (const { name, value, options } of cookiesToSet)
+            res.cookies.set(name, value, options);
+        },
+      },
+    });
+
+    const {
+      data: { user },
+    } = await supabase.auth.getUser();
+
+    const path = req.nextUrl.pathname;
+    const isProtected = opts.protectedPaths.some((p) => path === p || path.startsWith(`${p}/`));
+    if (isProtected && !user) {
+      const url = req.nextUrl.clone();
+      url.pathname = signInPath;
+      return NextResponse.redirect(url);
+    }
+
+    return res;
+  };
+}

package/src/rate-limit.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it } from "vitest";
+import { rateLimit } from "./rate-limit";
+
+describe("rateLimit", () => {
+  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);
+    expect(blocked.ok).toBe(false);
+    expect(blocked.retryAfterSeconds).toBeGreaterThan(0);
+  });
+
+  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
+  });
+});

package/src/rate-limit.ts

@@ -0,0 +1,48 @@
+// Lightweight in-memory sliding-window rate limiter 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).
+
+interface Bucket {
+  count: number;
+  resetAt: number;
+}
+
+const buckets = new Map<string, Bucket>();
+
+export interface RateLimitResult {
+  ok: boolean;
+  retryAfterSeconds: number;
+}
+
+export function rateLimit(key: string, limit: number, windowMs: number): RateLimitResult {
+  const now = Date.now();
+  const b = buckets.get(key);
+  if (!b || b.resetAt <= now) {
+    buckets.set(key, { count: 1, resetAt: now + windowMs });
+    return { ok: true, retryAfterSeconds: 0 };
+  }
+  if (b.count >= limit) {
+    return { ok: false, retryAfterSeconds: Math.ceil((b.resetAt - now) / 1000) };
+  }
+  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. */
+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";
+}
+
+/** Standard 429 JSON response for a tripped limit. */
+export function tooManyRequests(retryAfterSeconds: number): Response {
+  return new Response(JSON.stringify({ ok: false, error: "rate_limited" }), {
+    status: 429,
+    headers: { "content-type": "application/json", "retry-after": String(retryAfterSeconds) },
+  });
+}

package/src/routes.ts

@@ -0,0 +1,182 @@
+// Next.js App Router route-handler factory. Mount these in your app's
+// app/api/auth/**/route.ts files. Audit/analytics are emitted via the optional
+// `onEvent` hook — the package itself stores no observability data.
+
+import type { AuthenticationResponseJSON, RegistrationResponseJSON } from "@simplewebauthn/server";
+import { signInSchema, signUpSchema } from "./validation";
+import { createServerSupabase } from "./supabase";
+import { clearAal2Cookie, getSessionUser, setAal2Cookie } from "./guard";
+import {
+  createAuthenticationOptions,
+  createRegistrationOptions,
+  verifyAuthentication,
+  verifyRegistration,
+} from "./webauthn";
+import { clientIp, rateLimit, tooManyRequests } from "./rate-limit";
+import type { OnAuthEvent } from "./events";
+
+export type { AuthEvent, OnAuthEvent } from "./events";
+
+function json(data: unknown, status = 200): Response {
+  return new Response(JSON.stringify(data), {
+    status,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+export interface PasskeyAuthOptions {
+  /** Hook for audit/analytics/funnel. Errors here are swallowed (best-effort). */
+  onEvent?: OnAuthEvent;
+}
+
+export interface PasskeyAuthHandlers {
+  signUp: (req: Request) => Promise<Response>;
+  signIn: (req: Request) => Promise<Response>;
+  signOut: (req: Request) => Promise<Response>;
+  registerOptions: (req: Request) => Promise<Response>;
+  registerVerify: (req: Request) => Promise<Response>;
+  authenticateOptions: (req: Request) => Promise<Response>;
+  authenticateVerify: (req: Request) => Promise<Response>;
+}
+
+export function createPasskeyAuthHandlers(opts: PasskeyAuthOptions = {}): PasskeyAuthHandlers {
+  const emit: OnAuthEvent = async (e) => {
+    try {
+      await opts.onEvent?.(e);
+    } catch {
+      // best-effort: never let observability break auth
+    }
+  };
+
+  return {
+    async signUp(req) {
+      const limit = rateLimit(`signup:${clientIp(req)}`, 5, 10 * 60 * 1000);
+      if (!limit.ok) return tooManyRequests(limit.retryAfterSeconds);
+
+      let body: unknown;
+      try {
+        body = await req.json();
+      } catch {
+        return json({ ok: false, error: "unknown" }, 400);
+      }
+      const parsed = signUpSchema.safeParse(body);
+      if (!parsed.success) {
+        const field = parsed.error.issues[0]?.path[0];
+        return json(
+          { ok: false, error: field === "email" ? "validation_email" : "validation_password" },
+          400,
+        );
+      }
+      const supabase = await createServerSupabase();
+      const { data, error } = await supabase.auth.signUp({
+        email: parsed.data.email,
+        password: parsed.data.password,
+      });
+      if (error || !data.user) return json({ ok: false, error: "server" }, 400);
+      if (!data.session) {
+        return json({ ok: false, error: "email_confirmation_required" }, 400);
+      }
+      await emit({ type: "signup", userId: data.user.id });
+      return json({ ok: true });
+    },
+
+    async signIn(req) {
+      const limit = rateLimit(`signin:${clientIp(req)}`, 10, 5 * 60 * 1000);
+      if (!limit.ok) return tooManyRequests(limit.retryAfterSeconds);
+
+      let body: unknown;
+      try {
+        body = await req.json();
+      } catch {
+        return json({ ok: false, error: "unknown" }, 400);
+      }
+      const parsed = signInSchema.safeParse(body);
+      if (!parsed.success) {
+        const field = parsed.error.issues[0]?.path[0];
+        return json(
+          { ok: false, error: field === "email" ? "validation_email" : "validation_password" },
+          400,
+        );
+      }
+      const supabase = await createServerSupabase();
+      const { data, error } = await supabase.auth.signInWithPassword({
+        email: parsed.data.email,
+        password: parsed.data.password,
+      });
+      if (error || !data.user) {
+        await emit({ type: "signin_failure" });
+        return json({ ok: false, error: "invalid_credentials" }, 401);
+      }
+      // AAL1 only — not app-privileged until the passkey challenge succeeds.
+      return json({ ok: true });
+    },
+
+    async signOut() {
+      const supabase = await createServerSupabase();
+      const {
+        data: { user },
+      } = await supabase.auth.getUser();
+      await clearAal2Cookie();
+      await supabase.auth.signOut();
+      if (user) await emit({ type: "signout", userId: user.id });
+      return json({ ok: true });
+    },
+
+    async registerOptions() {
+      const user = await getSessionUser();
+      if (!user) return json({ ok: false, error: "server" }, 401);
+      const options = await createRegistrationOptions({ id: user.id, email: user.email ?? "" });
+      await emit({ type: "mfa_enroll_started", userId: user.id });
+      return json(options);
+    },
+
+    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);
+      if (!limit.ok) return tooManyRequests(limit.retryAfterSeconds);
+
+      let response: RegistrationResponseJSON;
+      try {
+        response = (await req.json()).response as RegistrationResponseJSON;
+      } catch {
+        return json({ ok: false, error: "unknown" }, 400);
+      }
+      const result = await verifyRegistration({ id: user.id, email: user.email ?? "" }, response);
+      if (!result.verified) return json({ ok: false, error: "verify" }, 400);
+
+      await setAal2Cookie(user.id);
+      await emit({ type: "mfa_enrolled", userId: user.id });
+      return json({ ok: true });
+    },
+
+    async authenticateOptions() {
+      const user = await getSessionUser();
+      if (!user) return json({ ok: false, error: "server" }, 401);
+      const options = await createAuthenticationOptions({ id: user.id, email: user.email ?? "" });
+      return json(options);
+    },
+
+    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);
+      if (!limit.ok) return tooManyRequests(limit.retryAfterSeconds);
+
+      let response: AuthenticationResponseJSON;
+      try {
+        response = (await req.json()).response as AuthenticationResponseJSON;
+      } catch {
+        return json({ ok: false, error: "unknown" }, 400);
+      }
+      const result = await verifyAuthentication({ id: user.id, email: user.email ?? "" }, response);
+      if (!result.verified) {
+        await emit({ type: "mfa_challenge_failure", userId: user.id });
+        return json({ ok: false, error: "verify" }, 401);
+      }
+      await setAal2Cookie(user.id);
+      await emit({ type: "signin_success", userId: user.id });
+      return json({ ok: true });
+    },
+  };
+}

package/src/supabase.ts

@@ -0,0 +1,40 @@
+import { createServerClient, type CookieOptions } from "@supabase/ssr";
+import { createClient } from "@supabase/supabase-js";
+import { cookies } from "next/headers";
+import { SUPABASE_ANON_KEY, SUPABASE_SERVICE_ROLE_KEY, SUPABASE_URL } from "./env";
+
+/**
+ * Request-scoped server client bound to the Next cookie store (App Router).
+ * Carries the user's AAL1 session; RLS keys on auth.uid(). SSR-safe.
+ */
+export async function createServerSupabase() {
+  const cookieStore = await cookies();
+  return createServerClient(SUPABASE_URL(), SUPABASE_ANON_KEY(), {
+    cookies: {
+      getAll() {
+        return cookieStore.getAll();
+      },
+      setAll(cookiesToSet: { name: string; value: string; options: CookieOptions }[]) {
+        try {
+          for (const { name, value, options } of cookiesToSet) {
+            cookieStore.set(name, value, options);
+          }
+        } catch {
+          // setAll called from a Server Component — safe to ignore; the
+          // middleware refresh path owns cookie writes.
+        }
+      },
+    },
+  });
+}
+
+/**
+ * Service-role client — bypasses RLS. SERVER-ONLY. Used strictly for
+ * server-controlled writes the user can't make under RLS (webauthn_challenges,
+ * credential counter updates). Never expose to the client.
+ */
+export function createServiceSupabase() {
+  return createClient(SUPABASE_URL(), SUPABASE_SERVICE_ROLE_KEY(), {
+    auth: { persistSession: false, autoRefreshToken: false },
+  });
+}

package/src/types.ts

@@ -0,0 +1,26 @@
+// Row types for the package's WebAuthn tables
+// (migrations/0001_passkey_tables.sql). Hand-written; replace with generated
+// Supabase types in your app if you prefer.
+
+export interface WebAuthnCredentialRow {
+  id: string;
+  user_id: string;
+  credential_id: string; // base64url
+  public_key: string; // base64url COSE key
+  counter: number;
+  transports: string[] | null;
+  device_type: string | null;
+  backed_up: boolean;
+  aaguid: string | null;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface WebAuthnChallengeRow {
+  id: string;
+  user_id: string;
+  challenge: string;
+  type: "registration" | "authentication";
+  expires_at: string;
+  created_at: string;
+}

package/src/validation.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from "vitest";
+import { passwordStrength, signInSchema, signUpSchema } from "./validation";
+
+describe("signUpSchema", () => {
+  it("accepts a valid email + 12+ char password", () => {
+    expect(signUpSchema.safeParse({ email: "a@example.com", password: "a strong pass" }).success).toBe(
+      true,
+    );
+  });
+  it("rejects an invalid email", () => {
+    const r = signUpSchema.safeParse({ email: "nope", password: "a strong pass" });
+    expect(r.success).toBe(false);
+    if (!r.success) expect(r.error.issues[0]?.path[0]).toBe("email");
+  });
+  it("rejects a password under 12 chars", () => {
+    const r = signUpSchema.safeParse({ email: "a@example.com", password: "short" });
+    expect(r.success).toBe(false);
+    if (!r.success) expect(r.error.issues[0]?.path[0]).toBe("password");
+  });
+});
+
+describe("signInSchema", () => {
+  it("requires a non-empty password but not the 12-char rule", () => {
+    expect(signInSchema.safeParse({ email: "a@example.com", password: "x" }).success).toBe(true);
+    expect(signInSchema.safeParse({ email: "a@example.com", password: "" }).success).toBe(false);
+  });
+});
+
+describe("passwordStrength", () => {
+  it("scores too-short as 0", () => {
+    expect(passwordStrength("short").score).toBe(0);
+  });
+  it("rewards length + passphrase spaces", () => {
+    expect(passwordStrength("correct horse battery staple").score).toBeGreaterThanOrEqual(3);
+  });
+});

package/src/validation.ts

@@ -0,0 +1,36 @@
+import { z } from "zod";
+
+// Password policy: length over complexity (a passphrase works well). ≥12 chars.
+export const PASSWORD_MIN = 12;
+
+export const emailSchema = z.string().trim().email();
+export const passwordSchema = z.string().min(PASSWORD_MIN);
+
+export const signUpSchema = z.object({
+  email: emailSchema,
+  password: passwordSchema,
+});
+
+export const signInSchema = z.object({
+  email: emailSchema,
+  password: z.string().min(1),
+});
+
+export type SignUpInput = z.infer<typeof signUpSchema>;
+export type SignInInput = z.infer<typeof signInSchema>;
+
+/** Password strength score 0–4 for a meter (provide a text equivalent in UI). */
+export function passwordStrength(password: string): {
+  score: 0 | 1 | 2 | 3 | 4;
+  label: "Too short" | "Weak" | "Fair" | "Good" | "Strong";
+} {
+  if (password.length < PASSWORD_MIN) return { score: 0, label: "Too short" };
+  let score = 1;
+  if (password.length >= 16) score++;
+  if (/\s/.test(password)) score++; // passphrase bonus (spaces)
+  if (/[^A-Za-z0-9]/.test(password) || (/[A-Za-z]/.test(password) && /[0-9]/.test(password)))
+    score++;
+  const clamped = Math.min(score, 4) as 0 | 1 | 2 | 3 | 4;
+  const label = (["Too short", "Weak", "Fair", "Good", "Strong"] as const)[clamped];
+  return { score: clamped, label };
+}