prod: update passkey, OAuth2, and core behavior

- Updated passkey plugin to use VerifiedPasskey types
- Removed legacy WebAuthn JSON handling
- Removed email_otp from second factor methods and updated types
- Added deterministicTokenHash for stable token generation
- Implemented rate limiting in email‑otp and magic‑link flows
- Refactored OAuth2 plugin to use an authorization‑code exchange
- Added idempotency support and updated docs, examples, and tests

Author: nikosgram

README.md

@@ -8,8 +8,8 @@ Type-safe, plugin-first authentication core for TypeScript applications.
 - Strongly typed register/authenticate payloads inferred from enabled plugins.
 - Path-based issue model (`{ message, path }`) for field-level error mapping.
 - Built-in methods: password, email OTP, magic link, OAuth2, passkey.
-- Built-in domain plugins: two-factor auth (TOTP/recovery), organizations/RBAC.
-- Framework-agnostic core (works with Next.js, SvelteKit, Workers, Node servers).
+- Built-in domain plugins: two-factor auth (TOTP/recovery code), organizations/RBAC.
+- Framework-agnostic core for TypeScript apps running in Node-compatible server environments.
 
 ## Install
 
@@ -164,19 +164,19 @@ createIssue("Generic failure");
 ### OAuth2 (Arctic)
 
 - Method: `"oauth2"`
-- Uses provider clients with `validateAuthorizationCode(...)` (Arctic-compatible).
+- Uses provider exchange callbacks. Arctic clients can be wrapped with `arcticAuthorizationCodeExchange(...)`.
 - Supports profile completion when required fields are missing.
 
 ```ts
 import { Google } from "arctic";
-import { oauth2Plugin } from "@oglofus/auth";
+import { arcticAuthorizationCodeExchange, oauth2Plugin } from "@oglofus/auth";
 
 const google = new Google(process.env.GOOGLE_CLIENT_ID!, process.env.GOOGLE_CLIENT_SECRET!, process.env.GOOGLE_REDIRECT_URI!);
 
 oauth2Plugin<AppUser, "google", "given_name" | "family_name">({
   providers: {
     google: {
-      client: google,
+      exchangeAuthorizationCode: arcticAuthorizationCodeExchange(google),
       resolveProfile: async ({ tokens }) => {
         const res = await fetch("https://openidconnect.googleapis.com/v1/userinfo", {
           headers: { Authorization: `Bearer ${tokens.accessToken()}` },
@@ -211,19 +211,23 @@ const result = await auth.authenticate({
   authorizationCode: "code-from-callback",
   redirectUri: process.env.GOOGLE_REDIRECT_URI!,
   codeVerifier: "pkce-code-verifier",
+  idempotencyKey: "oauth-state",
 });
 ```
 
 ### Passkey
 
 - Method: `"passkey"`
 - Register + authenticate supported.
+- The package consumes already-verified passkey results; it does not perform raw WebAuthn attestation/assertion verification.
+- Verify WebAuthn with `@simplewebauthn/server` or equivalent first, then pass the verified result into `auth.register(...)` / `auth.authenticate(...)`.
 - Config: `requiredProfileFields`, `passkeys` adapter.
 
 ### Two-Factor (Domain Plugin)
 
 - Method: `"two_factor"`
 - Adds post-primary verification (`TWO_FACTOR_REQUIRED`).
+- This release supports `totp` and `recovery_code`.
 - Uses `@oslojs/otp` internally for TOTP verification and enrollment URI generation.
 - Plugin API:
   - `beginTotpEnrollment(userId)`

docs/CONCEPT.md

@@ -92,8 +92,6 @@ export type AuthMethodName = PrimaryAuthMethod | (string & {});
 
 export type SecondFactorMethod =
   | "totp"
-  | "email_otp"
-  | "passkey"
   | "recovery_code";
 
 export type AccountDiscoveryMode = "private" | "explicit";
@@ -180,37 +178,45 @@ export type OAuth2AuthenticateInput<P extends string> = {
   provider: P;
   authorizationCode: string;
   redirectUri: string;
+  idempotencyKey?: string;
 };
 
 export type OAuth2RegisterInput<P extends string> = OAuth2AuthenticateInput<P>;
 
-// Keep this intentionally generic to avoid coupling core to specific WebAuthn helper libs.
-export type WebAuthnJson = Record<string, unknown>;
+export type VerifiedPasskeyRegistration = {
+  credentialId: string;
+  publicKey: string;
+  counter: number;
+  transports?: string[];
+};
+
+export type VerifiedPasskeyAuthentication = {
+  credentialId: string;
+  nextCounter: number;
+};
 
 export type PasskeyAuthenticateInput = {
   method: "passkey";
-  email?: string;
-  assertion: WebAuthnJson;
+  authentication: VerifiedPasskeyAuthentication;
 };
 
 export type PasskeyRegisterInput<U extends UserBase, K extends keyof U> = {
   method: "passkey";
   email: string;
-  attestation: WebAuthnJson;
+  registration: VerifiedPasskeyRegistration;
 } & LocalProfileFields<U, K>;
 
 export type TwoFactorVerifyInput =
   | { method: "totp"; pendingAuthId: string; code: string }
-  | { method: "email_otp"; pendingAuthId: string; code: string }
-  | { method: "passkey"; pendingAuthId: string; assertion: WebAuthnJson }
   | { method: "recovery_code"; pendingAuthId: string; code: string };
 
 export type ProfileCompletionState<U extends UserBase> = {
   pendingProfileId: string;
-  sourceMethod: "oauth2" | "passkey";
+  sourceMethod: AuthMethodName;
   email?: string;
   missingFields: readonly Extract<keyof U, string>[];
   prefill: Partial<U>;
+  continuation?: Record<string, unknown>;
 };
 
 export type CompleteProfileInput<U extends UserBase> = {
@@ -1443,7 +1449,7 @@ Keep wrappers thin so developer can swap providers later with minimal breakage.
 - OTP/magic-link send failures return explicit `DELIVERY_FAILED` (never silent event-only failures).
 - OTP/magic-link/2FA challenge consumption must be atomic to prevent replay races.
 - OTP verification must be bound to `challengeId` (never resolve active challenge only by email).
-- Passkey verification must validate challenge, origin, RP ID, and signature counter.
+- Passkey verification must validate challenge, origin, RP ID, and signature counter before calling this package; the package consumes already-verified passkey results.
 - OAuth2 callbacks must use `state`/PKCE and be idempotent against duplicate provider callbacks.
 - Session expiration + rotation support.
 - `accountDiscovery.mode = "private"` should avoid leaking user existence through explicit routing messages.
@@ -2347,9 +2353,9 @@ Fix in spec:
 - For email OTP verify/register, require and validate `challengeId` (avoid "latest challenge by email" lookup).
 - For out-of-band methods, use explicit delivery handlers for sending; use events only for observability/policy.
 - Use atomic compare-and-set for one-time credentials/challenges/recovery-code consumption.
-- For passkeys, strictly verify RP ID/origin/challenge and store updated counters after successful assertions.
+- For passkeys, require verified registration/authentication results from a WebAuthn library and store updated counters after successful assertions.
 - For 2FA, bind second-factor verification to `pendingAuthId` and consume challenge on success.
-- For OAuth/passkey partial signups, return `PROFILE_COMPLETION_REQUIRED` with missing fields and pending profile ID.
+- For OAuth partial signups, return `PROFILE_COMPLETION_REQUIRED` with missing fields and pending profile ID.
 - For organizations, enforce tenant scoping and membership status checks before permission/feature/limit evaluation.
 - For organizations, ensure bootstrap and seat-limited membership creation are atomic.
 - For organizations, validate role catalog on startup (default role, owner role, no cyclic inheritance).

examples/oauth2-google-arctic/README.md

@@ -2,9 +2,9 @@
 
 Files:
 
-- `auth.ts`: `oauth2Plugin` configured with Arctic `Google` client.
+- `auth.ts`: `oauth2Plugin` configured with Arctic `Google` client via `arcticAuthorizationCodeExchange(...)` and an idempotency adapter.
 - `start-route.ts`: starts OAuth flow and stores state + PKCE verifier in cookies.
-- `callback-route.ts`: validates callback and calls `auth.authenticate`.
+- `callback-route.ts`: validates callback and calls `auth.authenticate` with the callback `state` as `idempotencyKey`.
 
 Required environment variables:
 

examples/oauth2-google-arctic/auth.ts

@@ -1,7 +1,9 @@
 import {
   OglofusAuth,
+  arcticAuthorizationCodeExchange,
   oauth2Plugin,
   type OAuth2AccountAdapter,
+  type IdempotencyAdapter,
   type PendingProfileAdapter,
   type PendingProfileRecord,
   type Session,
@@ -21,6 +23,7 @@ const usersByEmail = new Map<string, AppUser>();
 const sessionsById = new Map<string, Session>();
 const linkedAccounts = new Map<string, string>();
 const pendingProfiles = new Map<string, PendingProfileRecord<AppUser>>();
+const seenCallbacks = new Set<string>();
 
 const users: UserAdapter<AppUser> = {
   findById: async (id) => usersById.get(id) ?? null,
@@ -92,6 +95,17 @@ const pending: PendingProfileAdapter<AppUser> = {
   },
 };
 
+const idempotency: IdempotencyAdapter = {
+  checkAndSet: async (key) => {
+    if (seenCallbacks.has(key)) {
+      return false;
+    }
+
+    seenCallbacks.add(key);
+    return true;
+  },
+};
+
 const google = new Google(
   process.env.GOOGLE_CLIENT_ID!,
   process.env.GOOGLE_CLIENT_SECRET!,
@@ -103,12 +117,13 @@ export const auth = new OglofusAuth({
     users,
     sessions,
     pendingProfiles: pending,
+    idempotency,
   },
   plugins: [
     oauth2Plugin<AppUser, "google", "given_name" | "family_name">({
       providers: {
         google: {
-          client: google,
+          exchangeAuthorizationCode: arcticAuthorizationCodeExchange(google),
           resolveProfile: async ({ tokens }) => {
             const response = await fetch("https://openidconnect.googleapis.com/v1/userinfo", {
               headers: {

examples/oauth2-google-arctic/callback-route.ts

@@ -18,6 +18,7 @@ export async function GET(request: NextRequest): Promise<NextResponse> {
     authorizationCode: code,
     redirectUri: process.env.GOOGLE_REDIRECT_URI!,
     codeVerifier,
+    idempotencyKey: state,
   });
 
   if (!result.ok) {

package-lock.json

@@ -26,7 +26,7 @@
     "LICENSE"
   ],
   "devDependencies": {
-    "@types/node": "^25.3.0",
+    "@types/node": "^25.3.5",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3"
   },