@vc1023/passkey-2fa 0.1.0

package/.env.example

@@ -0,0 +1,19 @@
+# @vc1023/passkey-2fa — required environment variables.
+# Copy the ones you need into your app's .env.local (and your host's env for
+# production). Run `npx passkey-2fa check-env` to verify them.
+
+# ─── Supabase (Settings → API) ───
+NEXT_PUBLIC_SUPABASE_URL=          # Project URL, e.g. https://abcd.supabase.co
+NEXT_PUBLIC_SUPABASE_ANON_KEY=     # anon / publishable key
+SUPABASE_SERVICE_ROLE_KEY=         # service_role / secret key — SERVER ONLY
+
+# ─── WebAuthn / passkey (your app's domain) ───
+# In production these are REQUIRED and validated (origin must be https, and
+# WEBAUTHN_RP_ID must equal the origin host). In local dev they default to
+# http://localhost:3000 / localhost.
+WEBAUTHN_ORIGIN=                   # e.g. https://yourapp.com
+WEBAUTHN_RP_ID=                    # e.g. yourapp.com  (registrable domain, no scheme/port)
+WEBAUTHN_RP_NAME=                  # display name shown in the passkey prompt, e.g. "Your App"
+
+# ─── AAL2 session token ───
+AUTH_MFA_SECRET=                   # HMAC secret for the 2FA session cookie — `openssl rand -hex 32`

package/README.md

@@ -0,0 +1,119 @@
+# @vc1023/passkey-2fa
+
+Drop-in **password + passkey (WebAuthn) 2FA** for **Next.js App Router + Supabase**.
+
+- Email + password = first factor (Supabase Auth, AAL1)
+- A **passkey** = mandatory second factor (custom WebAuthn, AAL2), enforced server-side
+- Single-use expiring challenges · replay-protected counter · session-bound AAL2 cookie · per-route rate limiting · fail-loud config
+
+It ships server route-handler factories, an Edge middleware factory, browser helpers, and the SQL migration. Audit/analytics stay yours via an `onEvent` hook.
+
+## 1. Install
+
+```bash
+npm install @vc1023/passkey-2fa
+```
+
+Add it to `transpilePackages` (it ships TypeScript source):
+
+```ts
+// next.config.ts
+const nextConfig = { transpilePackages: ["@vc1023/passkey-2fa"] };
+```
+
+## 2. Environment
+
+Copy `node_modules/@vc1023/passkey-2fa/.env.example` into `.env.local` and fill it. Then verify:
+
+```bash
+npx passkey-2fa check-env
+```
+
+| Var | Where |
+| --- | --- |
+| `NEXT_PUBLIC_SUPABASE_URL` / `NEXT_PUBLIC_SUPABASE_ANON_KEY` / `SUPABASE_SERVICE_ROLE_KEY` | Supabase → Settings → API |
+| `WEBAUTHN_ORIGIN` (`https://yourapp.com`) · `WEBAUTHN_RP_ID` (`yourapp.com`) · `WEBAUTHN_RP_NAME` | your app's domain |
+| `AUTH_MFA_SECRET` | `openssl rand -hex 32` |
+
+In **production** these are required and validated (origin must be https; RP-ID must equal the origin host) — the app fails loud if any is missing. In dev they default to `localhost`.
+
+> **Supabase setting:** disable email confirmation (Auth → Email) so the user is signed in immediately and can enroll a passkey in the same sign-up flow.
+
+## 3. Database
+
+Apply the migration to your Supabase project (SQL editor or `supabase db push`):
+
+```
+node_modules/@vc1023/passkey-2fa/migrations/0001_passkey_tables.sql
+```
+
+## 4. Mount the route handlers
+
+Create one file per endpoint under `app/api/auth/…`, all delegating to a shared instance:
+
+```ts
+// app/lib/auth.ts
+import { createPasskeyAuthHandlers } from "@vc1023/passkey-2fa/routes";
+
+export const handlers = createPasskeyAuthHandlers({
+  // optional: audit / analytics / funnel — never required
+  onEvent: async (e) => { /* e.type: "signup" | "signin_success" | "mfa_enrolled" | … */ },
+});
+```
+
+```ts
+// app/api/auth/sign-up/route.ts
+import { handlers } from "@/app/lib/auth";
+export const runtime = "nodejs";
+export const POST = handlers.signUp;
+```
+
+Repeat for: `sign-in` → `handlers.signIn`, `sign-out` → `handlers.signOut`,
+`webauthn/register/options` → `handlers.registerOptions`, `webauthn/register/verify` → `handlers.registerVerify`,
+`webauthn/authenticate/options` → `handlers.authenticateOptions`, `webauthn/authenticate/verify` → `handlers.authenticateVerify`.
+
+## 5. Middleware
+
+```ts
+// middleware.ts
+import { createPasskeyMiddleware } from "@vc1023/passkey-2fa/middleware";
+
+export const middleware = createPasskeyMiddleware({ protectedPaths: ["/dashboard"] });
+export const config = {
+  matcher: ["/((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp|ico)$).*)"],
+};
+```
+
+## 6. Protect a page (server-side AAL2 gate)
+
+```tsx
+// app/dashboard/page.tsx
+import { requireAal2, getSessionUser } from "@vc1023/passkey-2fa";
+export const dynamic = "force-dynamic";
+
+export default async function Dashboard() {
+  await requireAal2();            // redirects to /sign-in unless fully AAL2
+  const user = await getSessionUser();
+  return <p>Signed in as {user?.email}</p>;
+}
+```
+
+## 7. Build your UI with the client helpers
+
+You own the screens/copy; the package gives the network + ceremony:
+
+```tsx
+"use client";
+import {
+  signUp, enrollPasskey, signIn, challengePasskey, signOut, browserSupportsPasskeys,
+} from "@vc1023/passkey-2fa/client";
+
+// sign-up: await signUp(email, password) → if ok, await enrollPasskey()
+// sign-in: await signIn(email, password) → if ok, await challengePasskey()
+// each ceremony returns { ok:true } | { ok:false, reason:"cancelled"|"unsupported"|"error" }
+```
+
+## 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.
+- Server validation is enforced; you may also `signUpSchema.safeParse()` client-side for instant feedback.

package/bin/check-env.mjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+// `npx passkey-2fa check-env` — verify the env @vc1023/passkey-2fa needs.
+// Reads the project's .env.local (if present) merged over process.env, then
+// reports which required vars are set/missing. Exit 1 if any required is missing.
+
+import { readFileSync, existsSync } from "node:fs";
+import { resolve } from "node:path";
+
+const REQUIRED = [
+  "NEXT_PUBLIC_SUPABASE_URL",
+  "NEXT_PUBLIC_SUPABASE_ANON_KEY",
+  "SUPABASE_SERVICE_ROLE_KEY",
+  "WEBAUTHN_ORIGIN",
+  "WEBAUTHN_RP_ID",
+  "AUTH_MFA_SECRET",
+];
+const OPTIONAL = ["WEBAUTHN_RP_NAME", "NEXT_PUBLIC_APP_URL"];
+
+function loadEnvLocal() {
+  const out = {};
+  const file = resolve(process.cwd(), ".env.local");
+  if (!existsSync(file)) return out;
+  for (const raw of readFileSync(file, "utf8").split("\n")) {
+    const line = raw.trim();
+    if (!line || line.startsWith("#")) continue;
+    const eq = line.indexOf("=");
+    if (eq <= 0) continue;
+    out[line.slice(0, eq).trim()] = line
+      .slice(eq + 1)
+      .trim()
+      .replace(/\r$/, "");
+  }
+  return out;
+}
+
+const env = { ...loadEnvLocal(), ...process.env };
+const isSet = (k) => typeof env[k] === "string" && env[k].length > 0;
+
+console.log("\n@vc1023/passkey-2fa — env check\n");
+let missing = 0;
+for (const k of REQUIRED) {
+  const ok = isSet(k);
+  if (!ok) missing++;
+  console.log(`  ${ok ? "✓" : "✗"} ${k}${ok ? "" : "   (required, missing)"}`);
+}
+for (const k of OPTIONAL) {
+  console.log(`  ${isSet(k) ? "✓" : "·"} ${k}${isSet(k) ? "" : "   (optional)"}`);
+}
+
+if (missing > 0) {
+  console.error(
+    `\n${missing} required variable(s) missing. Copy .env.example, fill them, and re-run.` +
+      `\nSee node_modules/@vc1023/passkey-2fa/.env.example\n`,
+  );
+  process.exit(1);
+}
+console.log("\nAll required env present.\n");

package/migrations/0001_passkey_tables.sql

@@ -0,0 +1,64 @@
+-- @vc1023/passkey-2fa — apply this to your Supabase project (SQL editor
+-- or `supabase db push`). Creates the two tables the passkey 2FA layer needs,
+-- with default-deny RLS keyed on auth.uid(). Audit/analytics tables are NOT
+-- created here — wire those via the route handlers' onEvent hook in your app.
+
+create extension if not exists pgcrypto;
+
+-- updated_at trigger helper (idempotent).
+create or replace function set_updated_at()
+returns trigger language plpgsql as $$
+begin
+  new.updated_at = now();
+  return new;
+end;
+$$;
+
+-- ─── webauthn_credentials: a user's registered passkeys (the 2nd factor) ───
+create table if not exists webauthn_credentials (
+  id            uuid        primary key default gen_random_uuid(),
+  user_id       uuid        not null references auth.users (id) on delete cascade,
+  credential_id text        not null unique,
+  public_key    text        not null,
+  counter       bigint      not null default 0,
+  transports    text[],
+  device_type   text,
+  backed_up     boolean     not null default false,
+  aaguid        text,
+  created_at    timestamptz not null default now(),
+  updated_at    timestamptz not null default now()
+);
+
+create index if not exists idx_webauthn_credentials_user on webauthn_credentials (user_id);
+
+drop trigger if exists trg_webauthn_credentials_updated_at on webauthn_credentials;
+create trigger trg_webauthn_credentials_updated_at
+  before update on webauthn_credentials
+  for each row execute function set_updated_at();
+
+alter table webauthn_credentials enable row level security;
+
+drop policy if exists webauthn_credentials_select_own on webauthn_credentials;
+drop policy if exists webauthn_credentials_insert_own on webauthn_credentials;
+drop policy if exists webauthn_credentials_delete_own on webauthn_credentials;
+create policy webauthn_credentials_select_own on webauthn_credentials
+  for select using (auth.uid() = user_id);
+create policy webauthn_credentials_insert_own on webauthn_credentials
+  for insert with check (auth.uid() = user_id);
+create policy webauthn_credentials_delete_own on webauthn_credentials
+  for delete using (auth.uid() = user_id);
+
+-- ─── webauthn_challenges: single-use server-issued ceremony nonces ───
+create table if not exists webauthn_challenges (
+  id         uuid        primary key default gen_random_uuid(),
+  user_id    uuid        not null references auth.users (id) on delete cascade,
+  challenge  text        not null,
+  type       text        not null check (type in ('registration', 'authentication')),
+  expires_at timestamptz not null,
+  created_at timestamptz not null default now()
+);
+
+create index if not exists idx_webauthn_challenges_user_type on webauthn_challenges (user_id, type);
+
+-- Default-deny: RLS on, NO policies. Only the service role (server) touches it.
+alter table webauthn_challenges enable row level security;

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@vc1023/passkey-2fa",
+  "version": "0.1.0",
+  "description": "Drop-in password + passkey (WebAuthn) 2FA for Next.js App Router + Supabase.",
+  "license": "MIT",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./routes": "./src/routes.ts",
+    "./middleware": "./src/middleware.ts",
+    "./client": "./src/client.ts",
+    "./migrations/*": "./migrations/*"
+  },
+  "bin": {
+    "passkey-2fa": "./bin/check-env.mjs"
+  },
+  "files": [
+    "src",
+    "migrations",
+    "bin",
+    ".env.example",
+    "README.md"
+  ],
+  "keywords": [
+    "passkey",
+    "webauthn",
+    "2fa",
+    "mfa",
+    "supabase",
+    "next",
+    "auth"
+  ],
+  "dependencies": {
+    "@simplewebauthn/browser": "^13.1.0",
+    "@simplewebauthn/server": "^13.1.1",
+    "@supabase/ssr": "^0.5.2",
+    "@supabase/supabase-js": "^2.45.4",
+    "zod": "^3.23.8"
+  },
+  "peerDependencies": {
+    "next": ">=15",
+    "react": ">=19",
+    "react-dom": ">=19"
+  }
+}

package/src/aal2.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from "vitest";
+import { signAal2Token, verifyAal2Token } from "./aal2";
+
+const SECRET = "test-secret";
+const USER = "11111111-1111-1111-1111-111111111111";
+const SID = "sess-abc";
+const NOW = 1_700_000_000;
+
+describe("AAL2 token (session guard)", () => {
+  it("round-trips a valid token with sub + sid", () => {
+    const token = signAal2Token(USER, SID, SECRET, 3600, NOW);
+    expect(verifyAal2Token(token, SECRET, NOW + 10)).toEqual({ sub: USER, sid: SID });
+  });
+
+  it("rejects an expired token", () => {
+    const token = signAal2Token(USER, SID, SECRET, 60, NOW);
+    expect(verifyAal2Token(token, SECRET, NOW + 120)).toBeNull();
+  });
+
+  it("rejects a wrong secret", () => {
+    const token = signAal2Token(USER, SID, SECRET, 3600, NOW);
+    expect(verifyAal2Token(token, "other-secret", NOW + 10)).toBeNull();
+  });
+
+  it("rejects a tampered payload", () => {
+    const token = signAal2Token(USER, SID, SECRET, 3600, NOW);
+    const [, sig] = token.split(".");
+    const forged = `${Buffer.from(JSON.stringify({ sub: "attacker", sid: SID, exp: NOW + 3600 })).toString("base64url")}.${sig}`;
+    expect(verifyAal2Token(forged, SECRET, NOW + 10)).toBeNull();
+  });
+
+  it("rejects malformed / empty tokens", () => {
+    expect(verifyAal2Token(undefined, SECRET, NOW)).toBeNull();
+    expect(verifyAal2Token("", SECRET, NOW)).toBeNull();
+    expect(verifyAal2Token("no-dot", SECRET, NOW)).toBeNull();
+  });
+});

package/src/aal2.ts

@@ -0,0 +1,67 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+// AAL2 session marker. After a passkey ceremony verifies server-side, the app
+// issues a short-lived HMAC-signed token in an httpOnly cookie. The guard
+// requires BOTH a valid Supabase (AAL1) session AND a valid AAL2 token whose
+// `sub` matches the user (and, when present, whose `sid` matches the live
+// Supabase session) before granting app access. This is NOT an API bearer
+// credential — it only attests "this session completed the second factor".
+
+export const AAL2_COOKIE = "wlt_mfa";
+export const AAL2_TTL_SECONDS = 60 * 60; // 1h; re-challenge after.
+
+function b64url(input: Buffer | string): string {
+  return Buffer.from(input).toString("base64url");
+}
+
+export interface Aal2Claims {
+  sub: string; // user id
+  sid: string | null; // Supabase session id this AAL2 is bound to
+}
+
+interface Aal2Payload extends Aal2Claims {
+  exp: number; // epoch seconds
+}
+
+/** Mint a signed AAL2 token for `userId`, bound to the Supabase session `sid`. */
+export function signAal2Token(
+  userId: string,
+  sid: string | null,
+  secret: string,
+  ttlSeconds: number = AAL2_TTL_SECONDS,
+  nowSeconds: number = Math.floor(Date.now() / 1000),
+): string {
+  const payload: Aal2Payload = { sub: userId, sid, exp: nowSeconds + ttlSeconds };
+  const body = b64url(JSON.stringify(payload));
+  const sig = createHmac("sha256", secret).update(body).digest("base64url");
+  return `${body}.${sig}`;
+}
+
+/**
+ * Verify an AAL2 token. Returns its claims (`sub`, `sid`) if the signature is
+ * valid (timing-safe) and unexpired; otherwise null. Never throws. Callers must
+ * still check `sub` against the signed-in user and `sid` against the live session.
+ */
+export function verifyAal2Token(
+  token: string | undefined | null,
+  secret: string,
+  nowSeconds: number = Math.floor(Date.now() / 1000),
+): Aal2Claims | null {
+  if (!token) return null;
+  const dot = token.indexOf(".");
+  if (dot <= 0) return null;
+  const body = token.slice(0, dot);
+  const sig = token.slice(dot + 1);
+  const expected = createHmac("sha256", secret).update(body).digest("base64url");
+  const sigBuf = Buffer.from(sig);
+  const expBuf = Buffer.from(expected);
+  if (sigBuf.length !== expBuf.length || !timingSafeEqual(sigBuf, expBuf)) return null;
+  try {
+    const payload = JSON.parse(Buffer.from(body, "base64url").toString()) as Aal2Payload;
+    if (typeof payload.sub !== "string" || typeof payload.exp !== "number") return null;
+    if (payload.exp < nowSeconds) return null;
+    return { sub: payload.sub, sid: payload.sid ?? null };
+  } catch {
+    return null;
+  }
+}

package/src/api-client.ts

@@ -0,0 +1,58 @@
+// Client-side POST helpers used by ./client. `postJSON` discriminates network
+// vs server failures; `postForOptions` returns raw JSON for the WebAuthn options
+// endpoints (which return the ceremony options object directly).
+
+export type ApiErrorCode =
+  | "validation_email"
+  | "validation_password"
+  | "invalid_credentials"
+  | "email_confirmation_required"
+  | "network"
+  | "server"
+  | "unknown"
+  | "verify"
+  | "rate_limited";
+
+export interface ApiResult {
+  ok: boolean;
+  error?: ApiErrorCode;
+  data?: unknown;
+}
+
+export async function postJSON(url: string, body?: unknown): Promise<ApiResult> {
+  let res: Response;
+  try {
+    res = await fetch(url, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: body !== undefined ? JSON.stringify(body) : undefined,
+    });
+  } catch {
+    return { ok: false, error: "network" };
+  }
+
+  let data: Record<string, unknown> = {};
+  try {
+    data = (await res.json()) as Record<string, unknown>;
+  } catch {
+    // non-JSON
+  }
+
+  if (res.ok && data.ok) return { ok: true, data };
+  return { ok: false, error: (data.error as ApiErrorCode) ?? "server" };
+}
+
+/** POST returning the raw parsed JSON body on a 2xx, or null on failure. Used for
+ *  the WebAuthn options endpoints (no `{ ok: true }` envelope). */
+export async function postForOptions(url: string): Promise<Record<string, unknown> | null> {
+  try {
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+    });
+    if (!res.ok) return null;
+    return (await res.json()) as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+}

package/src/client.ts

@@ -0,0 +1,86 @@
+"use client";
+
+// Browser helpers. They assume the route handlers are mounted under /api/auth
+// (the documented convention). signUp/signIn/signOut wrap the credential
+// endpoints; enrollPasskey/challengePasskey run the full WebAuthn ceremony +
+// verify and return a UI-friendly result.
+
+import {
+  browserSupportsWebAuthn,
+  startAuthentication,
+  startRegistration,
+  type PublicKeyCredentialCreationOptionsJSON,
+  type PublicKeyCredentialRequestOptionsJSON,
+} from "@simplewebauthn/browser";
+import { postForOptions, postJSON, type ApiResult } from "./api-client";
+
+const BASE = "/api/auth";
+
+export type { ApiResult, ApiErrorCode } from "./api-client";
+
+// Isomorphic validation re-exported here so client components get it without
+// importing the server barrel (which pulls node:crypto + next/headers).
+export {
+  signUpSchema,
+  signInSchema,
+  passwordStrength,
+  PASSWORD_MIN,
+  type SignUpInput,
+  type SignInInput,
+} from "./validation";
+
+export type CeremonyResult = { ok: true } | { ok: false; reason: "cancelled" | "unsupported" | "error" };
+
+/** True if this browser can do WebAuthn / passkeys. */
+export function browserSupportsPasskeys(): boolean {
+  return browserSupportsWebAuthn();
+}
+
+export function signUp(email: string, password: string): Promise<ApiResult> {
+  return postJSON(`${BASE}/sign-up`, { email, password });
+}
+
+export function signIn(email: string, password: string): Promise<ApiResult> {
+  return postJSON(`${BASE}/sign-in`, { email, password });
+}
+
+export function signOut(): Promise<ApiResult> {
+  return postJSON(`${BASE}/sign-out`);
+}
+
+/** Enroll a passkey (sign-up step 2). Runs the registration ceremony + verify. */
+export async function enrollPasskey(): Promise<CeremonyResult> {
+  const options = await postForOptions(`${BASE}/webauthn/register/options`);
+  if (!options) return { ok: false, reason: "error" };
+  let attResp;
+  try {
+    attResp = await startRegistration({
+      optionsJSON: options as unknown as PublicKeyCredentialCreationOptionsJSON,
+    });
+  } catch (err) {
+    const name = (err as Error)?.name;
+    if (name === "NotAllowedError" || name === "AbortError") return { ok: false, reason: "cancelled" };
+    if (name === "NotSupportedError") return { ok: false, reason: "unsupported" };
+    return { ok: false, reason: "error" };
+  }
+  const verify = await postJSON(`${BASE}/webauthn/register/verify`, { response: attResp });
+  return verify.ok ? { ok: true } : { ok: false, reason: "error" };
+}
+
+/** Run the passkey challenge (sign-in step 2). */
+export async function challengePasskey(): Promise<CeremonyResult> {
+  const options = await postForOptions(`${BASE}/webauthn/authenticate/options`);
+  if (!options) return { ok: false, reason: "error" };
+  let authResp;
+  try {
+    authResp = await startAuthentication({
+      optionsJSON: options as unknown as PublicKeyCredentialRequestOptionsJSON,
+    });
+  } catch (err) {
+    const name = (err as Error)?.name;
+    if (name === "NotAllowedError" || name === "AbortError") return { ok: false, reason: "cancelled" };
+    return { ok: false, reason: "error" };
+  }
+  const verify = await postJSON(`${BASE}/webauthn/authenticate/verify`, { response: authResp });
+  return verify.ok ? { ok: true } : { ok: false, reason: "error" };
+}

package/src/config.ts

@@ -0,0 +1,63 @@
+// WebAuthn + AAL2 configuration, read from env (env-only convention). Dev
+// defaults are baked in; in production a missing/invalid value throws at use
+// (fail-loud) rather than shipping a localhost RP-ID or an insecure origin.
+
+function isProd(): boolean {
+  return process.env.VERCEL_ENV === "production" || process.env.NODE_ENV === "production";
+}
+
+function fromEnvOrDevDefault(name: string, devDefault: string): string {
+  const value = process.env[name];
+  if (value && value.length > 0) return value;
+  if (isProd()) {
+    throw new Error(
+      `[@vc1023/passkey-2fa] Missing required production env: ${name}. ` +
+        `A dev default (${devDefault}) is only used outside production.`,
+    );
+  }
+  return devDefault;
+}
+
+/** Expected origin of the WebAuthn ceremony (scheme + host + port). https in prod. */
+export function expectedOrigin(): string {
+  const origin = fromEnvOrDevDefault("WEBAUTHN_ORIGIN", "http://localhost:3000");
+  if (isProd() && !origin.startsWith("https://")) {
+    throw new Error(
+      `[@vc1023/passkey-2fa] WEBAUTHN_ORIGIN must be https:// in production (got "${origin}").`,
+    );
+  }
+  return origin;
+}
+
+/** WebAuthn Relying Party ID — registrable domain (no scheme/port). In prod it
+ *  MUST equal the WEBAUTHN_ORIGIN host. */
+export function rpID(): string {
+  const id = fromEnvOrDevDefault("WEBAUTHN_RP_ID", "localhost");
+  if (isProd()) {
+    let host = "";
+    try {
+      host = new URL(expectedOrigin()).hostname;
+    } catch {
+      host = "";
+    }
+    if (id !== host) {
+      throw new Error(
+        `[@vc1023/passkey-2fa] WEBAUTHN_RP_ID ("${id}") must equal the WEBAUTHN_ORIGIN host ("${host}") in production.`,
+      );
+    }
+  }
+  return id;
+}
+
+export function rpName(): string {
+  return process.env.WEBAUTHN_RP_NAME || "Passkey 2FA";
+}
+
+export function appUrl(): string {
+  return fromEnvOrDevDefault("NEXT_PUBLIC_APP_URL", "http://localhost:3000");
+}
+
+/** HMAC secret for the AAL2 session token. MUST be set in production. */
+export function mfaSecret(): string {
+  return fromEnvOrDevDefault("AUTH_MFA_SECRET", "dev-insecure-mfa-secret-do-not-use-in-prod");
+}

package/src/env.ts

@@ -0,0 +1,20 @@
+// Env access with fail-loud semantics — a missing required value throws at call
+// time with a clear, named message rather than letting the app boot broken.
+
+export function requireEnv(name: string, value: string | undefined): string {
+  if (!value || value.length === 0) {
+    throw new Error(
+      `[@vc1023/passkey-2fa] Missing required environment variable: ${name}. ` +
+        `Set it in .env.local (local) and your host's env (deployed). ` +
+        `Run \`npx passkey-2fa check-env\` to see everything that's required.`,
+    );
+  }
+  return value;
+}
+
+export const SUPABASE_URL = () =>
+  requireEnv("NEXT_PUBLIC_SUPABASE_URL", process.env.NEXT_PUBLIC_SUPABASE_URL);
+export const SUPABASE_ANON_KEY = () =>
+  requireEnv("NEXT_PUBLIC_SUPABASE_ANON_KEY", process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY);
+export const SUPABASE_SERVICE_ROLE_KEY = () =>
+  requireEnv("SUPABASE_SERVICE_ROLE_KEY", process.env.SUPABASE_SERVICE_ROLE_KEY);

package/src/events.ts

@@ -0,0 +1,14 @@
+// Auth lifecycle events emitted by the route handlers. Wire an `onEvent` handler
+// (see ./routes) to plug in your own audit log, analytics, or funnel — the
+// package stays free of any app-specific observability contract.
+
+export type AuthEvent =
+  | { type: "signup"; userId: string }
+  | { type: "signin_failure" }
+  | { type: "signin_success"; userId: string }
+  | { type: "mfa_enroll_started"; userId: string }
+  | { type: "mfa_enrolled"; userId: string }
+  | { type: "mfa_challenge_failure"; userId: string }
+  | { type: "signout"; userId: string };
+
+export type OnAuthEvent = (event: AuthEvent) => void | Promise<void>;