@robelest/convex-auth 0.0.4-preview.21 → 0.0.4-preview.23

package/dist/server/oauth.js

@@ -1,7 +1,7 @@
-import { AuthError } from "./authError.js";
 import { isLocalHost, logWithLevel } from "./utils.js";
 import { SHARED_COOKIE_OPTIONS } from "./cookies.js";
 import { Fx } from "@robelest/fx";
+import { Cv } from "@robelest/fx/convex";
 import * as arctic from "arctic";
 
 //#region src/server/oauth.ts
@@ -10,7 +10,7 @@ import * as arctic from "arctic";
 *
 * Uses Arctic for OAuth provider integration.
 *
-* All functions return `Fx<A, AuthError>` composed via `Fx.gen` pipelines.
+* All functions return `Fx<A, ConvexError<any>>` composed via `Fx.gen` pipelines.
 *
 * @internal
 * @module
@@ -59,15 +59,24 @@ function isPKCEProvider(provider) {
 }
 /**
 * Exchange the authorization code for tokens via Arctic.
-* Maps Arctic-specific errors to typed `AuthError` failures.
+* Maps Arctic-specific errors to typed `ConvexError<any>` failures.
 */
 function exchangeCode(arcticProvider, code, codeVerifier) {
 	return Fx.from({
 		ok: () => isPKCEProvider(arcticProvider) ? arcticProvider.validateAuthorizationCode(code, codeVerifier) : arcticProvider.validateAuthorizationCode(code),
 		err: (e) => {
-			if (e instanceof arctic.OAuth2RequestError) return new AuthError("OAUTH_PROVIDER_ERROR", `Token exchange failed: ${e.code}`);
-			if (e instanceof arctic.ArcticFetchError) return new AuthError("OAUTH_PROVIDER_ERROR", `Network error during token exchange: ${e.message}`);
-			return new AuthError("OAUTH_PROVIDER_ERROR", `Unexpected error during token exchange: ${e instanceof Error ? e.message : String(e)}`);
+			if (e instanceof arctic.OAuth2RequestError) return Cv.error({
+				code: "OAUTH_PROVIDER_ERROR",
+				message: `Token exchange failed: ${e.code}`
+			});
+			if (e instanceof arctic.ArcticFetchError) return Cv.error({
+				code: "OAUTH_PROVIDER_ERROR",
+				message: `Network error during token exchange: ${e.message}`
+			});
+			return Cv.error({
+				code: "OAUTH_PROVIDER_ERROR",
+				message: `Unexpected error during token exchange: ${e instanceof Error ? e.message : String(e)}`
+			});
 		}
 	}).pipe(Fx.chain((tokens) => {
 		return Fx.succeed(tokens);
@@ -83,7 +92,10 @@ function extractProfile(providerId, oauthConfig, tokens) {
 	return Fx.match(profileSource, profileSource.source, {
 		callback: (_profileSource) => Fx.from({
 			ok: () => oauthConfig.profile(tokens),
-			err: (e) => new AuthError("OAUTH_INVALID_PROFILE", `Profile callback threw: ${e instanceof Error ? e.message : String(e)}`)
+			err: (e) => Cv.error({
+				code: "OAUTH_INVALID_PROFILE",
+				message: `Profile callback threw: ${e instanceof Error ? e.message : String(e)}`
+			})
 		}),
 		idToken: (_profileSource) => {
 			const claims = arctic.decodeIdToken(tokens.idToken());
@@ -94,14 +106,20 @@ function extractProfile(providerId, oauthConfig, tokens) {
 				image: claims.picture ?? void 0
 			});
 		},
-		missing: (_profileSource) => Fx.fail(new AuthError("OAUTH_INVALID_PROFILE", `Provider "${providerId}" does not return an ID token. Add a \`profile\` callback in the OAuth() config to extract user info from the access token.`))
+		missing: (_profileSource) => Cv.fail({
+			code: "OAUTH_INVALID_PROFILE",
+			message: `Provider "${providerId}" does not return an ID token. Add a \`profile\` callback in the OAuth() config to extract user info from the access token.`
+		})
 	});
 }
 /**
 * Validate that the profile has a non-empty string `id`.
 */
 function validateProfileId(providerId, profile) {
-	return typeof profile.id === "string" && profile.id ? Fx.succeed(profile) : Fx.fail(new AuthError("OAUTH_INVALID_PROFILE", `The profile callback for "${providerId}" must return an object with a string \`id\` field.`));
+	return typeof profile.id === "string" && profile.id ? Fx.succeed(profile) : Cv.fail({
+		code: "OAUTH_INVALID_PROFILE",
+		message: `The profile callback for "${providerId}" must return an object with a string \`id\` field.`
+	});
 }
 /**
 * Create an OAuth authorization URL using an Arctic provider.
@@ -145,7 +163,7 @@ async function createOAuthAuthorizationURL(providerId, arcticProvider, oauthConf
 * Handle the OAuth callback: validate state, exchange code for tokens,
 * extract profile.
 *
-* Returns `Fx<CallbackResult, AuthError>` composed via `Fx.gen`.
+* Returns `Fx<CallbackResult, ConvexError<any>>` composed via `Fx.gen`.
 */
 /** @internal */
 function handleOAuthCallback(providerId, arcticProvider, oauthConfig, params, cookies) {
@@ -153,7 +171,10 @@ function handleOAuthCallback(providerId, arcticProvider, oauthConfig, params, co
 		const resCookies = [];
 		const storedState = cookies[oauthCookieName("state", providerId)];
 		const returnedState = params.state;
-		yield* Fx.guard(!storedState || !returnedState || storedState !== returnedState, Fx.fail(new AuthError("OAUTH_INVALID_STATE")));
+		yield* Fx.guard(!storedState || !returnedState || storedState !== returnedState, Cv.fail({
+			code: "OAUTH_INVALID_STATE",
+			message: "Invalid OAuth state. Please try signing in again."
+		}));
 		resCookies.push(clearCookie("state", providerId));
 		if (params.error) {
 			const cause = {
@@ -162,25 +183,41 @@ function handleOAuthCallback(providerId, arcticProvider, oauthConfig, params, co
 				error_description: params.error_description
 			};
 			logWithLevel("DEBUG", "OAuthCallbackError", cause);
-			yield* Fx.fail(new AuthError("OAUTH_PROVIDER_ERROR", "OAuth provider returned an error", { cause: JSON.stringify(cause) }));
+			yield* Cv.fail({
+				code: "OAUTH_PROVIDER_ERROR",
+				message: "OAuth provider returned an error",
+				cause: JSON.stringify(cause)
+			});
 		}
-		const code = yield* params.code != null ? Fx.succeed(params.code) : Fx.fail(new AuthError("OAUTH_PROVIDER_ERROR", "Missing authorization code in callback"));
+		const code = yield* params.code != null ? Fx.succeed(params.code) : Cv.fail({
+			code: "OAUTH_PROVIDER_ERROR",
+			message: "Missing authorization code in callback"
+		});
 		let codeVerifier;
 		if (isPKCEProvider(arcticProvider)) {
 			const pkceCookieName = oauthCookieName("pkce", providerId);
-			codeVerifier = yield* cookies[pkceCookieName] != null ? Fx.succeed(cookies[pkceCookieName]) : Fx.fail(new AuthError("OAUTH_MISSING_VERIFIER", "Missing PKCE verifier cookie for OAuth callback"));
+			codeVerifier = yield* cookies[pkceCookieName] != null ? Fx.succeed(cookies[pkceCookieName]) : Cv.fail({
+				code: "OAUTH_MISSING_VERIFIER",
+				message: "Missing PKCE verifier cookie for OAuth callback"
+			});
 			resCookies.push(clearCookie("pkce", providerId));
 		}
 		let nonce;
 		if (oauthConfig.nonce === true) {
 			const nonceCookieName = oauthCookieName("nonce", providerId);
-			nonce = yield* cookies[nonceCookieName] != null ? Fx.succeed(cookies[nonceCookieName]) : Fx.fail(new AuthError("OAUTH_PROVIDER_ERROR", "Missing nonce cookie for OAuth callback"));
+			nonce = yield* cookies[nonceCookieName] != null ? Fx.succeed(cookies[nonceCookieName]) : Cv.fail({
+				code: "OAUTH_PROVIDER_ERROR",
+				message: "Missing nonce cookie for OAuth callback"
+			});
 			resCookies.push(clearCookie("nonce", providerId));
 		}
 		const tokens = yield* exchangeCode(arcticProvider, code, codeVerifier);
 		if (oauthConfig.validateTokens !== void 0) yield* Fx.from({
 			ok: () => oauthConfig.validateTokens(tokens, { nonce }),
-			err: (e) => new AuthError("OAUTH_PROVIDER_ERROR", `Token validation failed: ${e instanceof Error ? e.message : String(e)}`)
+			err: (e) => Cv.error({
+				code: "OAUTH_PROVIDER_ERROR",
+				message: `Token validation failed: ${e instanceof Error ? e.message : String(e)}`
+			})
 		});
 		const profile = yield* validateProfileId(providerId, yield* extractProfile(providerId, oauthConfig, tokens));
 		logWithLevel("DEBUG", "OAuth callback profile extracted", {

package/dist/server/oauth.js.map

@@ -1 +1 @@
-{"version":3,"file":"oauth.js","names":[],"sources":["../../src/server/oauth.ts"],"sourcesContent":["/**\n * Arctic-based OAuth flow implementation.\n *\n * Uses Arctic for OAuth provider integration.\n *\n * All functions return `Fx<A, AuthError>` composed via `Fx.gen` pipelines.\n *\n * @internal\n * @module\n */\n\nimport { Fx } from \"@robelest/fx\";\nimport * as arctic from \"arctic\";\n\nimport { SHARED_COOKIE_OPTIONS } from \"./cookies\";\nimport { AuthError } from \"./authError\";\nimport type { OAuthProfile } from \"./types\";\nimport { logWithLevel } from \"./utils\";\nimport { isLocalHost } from \"./utils\";\n\ntype OAuthProviderConfigLike = {\n  scopes?: string[];\n  profile?: (tokens: arctic.OAuth2Tokens) => Promise<OAuthProfile>;\n  nonce?: boolean;\n  validateTokens?: (\n    tokens: arctic.OAuth2Tokens,\n    ctx: { nonce?: string },\n  ) => Promise<void>;\n};\n\n// ============================================================================\n// Types\n// ============================================================================\n\n/** A cookie to be set on the HTTP response. */\n/** @internal */\nexport interface OAuthCookie {\n  name: string;\n  value: string;\n  options: Record<string, unknown>;\n}\n\n/** Result of creating an authorization URL. */\n/** @internal */\nexport interface AuthorizationResult {\n  redirect: string;\n  cookies: OAuthCookie[];\n  signature: string;\n}\n\n/** Result of handling an OAuth callback. */\n/** @internal */\nexport interface CallbackResult {\n  profile: OAuthProfile;\n  providerAccountId: string;\n  cookies: OAuthCookie[];\n  signature: string;\n}\n\n// ============================================================================\n// Cookie helpers\n// ============================================================================\n\nconst COOKIE_TTL = 60 * 15; // 15 minutes\n\nfunction oauthCookieName(type: \"state\" | \"pkce\" | \"nonce\", providerId: string) {\n  const prefix = !isLocalHost(process.env.CONVEX_SITE_URL) ? \"__Host-\" : \"\";\n  return prefix + providerId + \"OAuth\" + type;\n}\n\nfunction createCookie(\n  type: \"state\" | \"pkce\" | \"nonce\",\n  providerId: string,\n  value: string,\n): OAuthCookie {\n  const expires = new Date();\n  expires.setTime(expires.getTime() + COOKIE_TTL * 1000);\n  return {\n    name: oauthCookieName(type, providerId),\n    value,\n    options: { ...SHARED_COOKIE_OPTIONS, expires },\n  };\n}\n\nfunction clearCookie(\n  type: \"state\" | \"pkce\" | \"nonce\",\n  providerId: string,\n): OAuthCookie {\n  return {\n    name: oauthCookieName(type, providerId),\n    value: \"\",\n    options: { ...SHARED_COOKIE_OPTIONS, maxAge: 0 },\n  };\n}\n\n// ============================================================================\n// Signature (ConvexAuth-specific verifier mechanism)\n// ============================================================================\n\n/**\n * Creates a signature string from the OAuth state parameters.\n * This is stored in the verifier table and validated during callback.\n */\n/** @internal */\nexport function getAuthorizationSignature({\n  codeVerifier,\n  state,\n}: {\n  codeVerifier?: string;\n  state?: string;\n}) {\n  return [codeVerifier, state].filter((param) => param !== undefined).join(\" \");\n}\n\n// ============================================================================\n// PKCE Detection\n// ============================================================================\n\n/**\n * Detect whether an Arctic provider uses PKCE by checking the arity\n * of `createAuthorizationURL`. PKCE providers take 3 args\n * (state, codeVerifier, scopes), non-PKCE take 2 (state, scopes).\n */\nfunction isPKCEProvider(provider: any): boolean {\n  return (\n    typeof provider.createAuthorizationURL === \"function\" &&\n    provider.createAuthorizationURL.length >= 3\n  );\n}\n\n// ============================================================================\n// Token exchange — wraps Arctic's validateAuthorizationCode\n// ============================================================================\n\n/**\n * Exchange the authorization code for tokens via Arctic.\n * Maps Arctic-specific errors to typed `AuthError` failures.\n */\nfunction exchangeCode(\n  arcticProvider: any,\n  code: string,\n  codeVerifier: string | undefined,\n): Fx<arctic.OAuth2Tokens, AuthError> {\n  return Fx.from({\n    ok: () =>\n      isPKCEProvider(arcticProvider)\n        ? arcticProvider.validateAuthorizationCode(code, codeVerifier)\n        : arcticProvider.validateAuthorizationCode(code),\n    err: (e) => {\n      if (e instanceof arctic.OAuth2RequestError) {\n        return new AuthError(\n          \"OAUTH_PROVIDER_ERROR\",\n          `Token exchange failed: ${e.code}`,\n        );\n      }\n      if (e instanceof arctic.ArcticFetchError) {\n        return new AuthError(\n          \"OAUTH_PROVIDER_ERROR\",\n          `Network error during token exchange: ${e.message}`,\n        );\n      }\n      // Unknown error — treat as unrecoverable defect; we surface it as\n      // an AuthError here so the pipeline type stays Fx<_, AuthError>.\n      // The original `throw e` re-throw is replicated via Fx.fatal below.\n      return new AuthError(\n        \"OAUTH_PROVIDER_ERROR\",\n        `Unexpected error during token exchange: ${e instanceof Error ? e.message : String(e)}`,\n      );\n    },\n  }).pipe(\n    Fx.chain((tokens) => {\n      // If the original error was neither OAuth2RequestError nor\n      // ArcticFetchError the old code re-threw it raw. We replicate that\n      // by checking whether we created an \"Unexpected\" marker message\n      // — but since `Fx.from` already mapped it, we just pass through.\n      return Fx.succeed(tokens);\n    }),\n  );\n}\n\n/**\n * Extract the user profile from tokens using the config callback,\n * OIDC auto-decode, or fail if neither is available.\n */\nfunction extractProfile(\n  providerId: string,\n  oauthConfig: OAuthProviderConfigLike,\n  tokens: arctic.OAuth2Tokens,\n): Fx<OAuthProfile, AuthError> {\n  const hasIdToken =\n    \"id_token\" in tokens.data &&\n    typeof (tokens.data as any).id_token === \"string\";\n  const profileSource = oauthConfig.profile\n    ? { source: \"callback\" as const }\n    : hasIdToken\n      ? { source: \"idToken\" as const }\n      : { source: \"missing\" as const };\n\n  return Fx.match(profileSource, profileSource.source, {\n    callback: (_profileSource) =>\n      Fx.from({\n        ok: () => oauthConfig.profile!(tokens),\n        err: (e) =>\n          new AuthError(\n            \"OAUTH_INVALID_PROFILE\",\n            `Profile callback threw: ${e instanceof Error ? e.message : String(e)}`,\n          ),\n      }),\n    idToken: (_profileSource) => {\n      const claims = arctic.decodeIdToken(tokens.idToken()) as Record<\n        string,\n        unknown\n      >;\n      return Fx.succeed({\n        id: (claims.sub as string) ?? crypto.randomUUID(),\n        name: (claims.name as string) ?? undefined,\n        email: (claims.email as string) ?? undefined,\n        image: (claims.picture as string) ?? undefined,\n      });\n    },\n    missing: (_profileSource) =>\n      Fx.fail(\n        new AuthError(\n          \"OAUTH_INVALID_PROFILE\",\n          `Provider \"${providerId}\" does not return an ID token. ` +\n            `Add a \\`profile\\` callback in the OAuth() config to extract user info from the access token.`,\n        ),\n      ),\n  });\n}\n\n/**\n * Validate that the profile has a non-empty string `id`.\n */\nfunction validateProfileId(\n  providerId: string,\n  profile: OAuthProfile,\n): Fx<OAuthProfile, AuthError> {\n  return typeof profile.id === \"string\" && profile.id\n    ? Fx.succeed(profile)\n    : Fx.fail(\n        new AuthError(\n          \"OAUTH_INVALID_PROFILE\",\n          `The profile callback for \"${providerId}\" must return an object with a string \\`id\\` field.`,\n        ),\n      );\n}\n\n// ============================================================================\n// Authorization URL creation\n// ============================================================================\n\n/**\n * Create an OAuth authorization URL using an Arctic provider.\n *\n * Handles PKCE detection, state generation, and cookie creation.\n */\n/** @internal */\nexport async function createOAuthAuthorizationURL(\n  providerId: string,\n  arcticProvider: any,\n  oauthConfig: OAuthProviderConfigLike,\n): Promise<AuthorizationResult> {\n  const state = arctic.generateState();\n  const cookies: OAuthCookie[] = [];\n  let codeVerifier: string | undefined;\n\n  const scopes = oauthConfig.scopes ?? [];\n\n  let url: URL;\n\n  if (isPKCEProvider(arcticProvider)) {\n    codeVerifier = arctic.generateCodeVerifier();\n    url = arcticProvider.createAuthorizationURL(state, codeVerifier, scopes);\n    cookies.push(createCookie(\"pkce\", providerId, codeVerifier));\n  } else {\n    url = arcticProvider.createAuthorizationURL(state, scopes);\n  }\n\n  cookies.push(createCookie(\"state\", providerId, state));\n\n  if (oauthConfig.nonce === true) {\n    const nonce = arctic.generateState();\n    url.searchParams.set(\"nonce\", nonce);\n    cookies.push(createCookie(\"nonce\", providerId, nonce));\n  }\n\n  logWithLevel(\"DEBUG\", \"OAuth authorization URL created\", {\n    url: url.toString(),\n    providerId,\n    hasPKCE: !!codeVerifier,\n  });\n\n  const signature = getAuthorizationSignature({ codeVerifier, state });\n\n  return {\n    redirect: url.toString(),\n    cookies,\n    signature,\n  };\n}\n\n// ============================================================================\n// OAuth callback handling\n// ============================================================================\n\n/**\n * Handle the OAuth callback: validate state, exchange code for tokens,\n * extract profile.\n *\n * Returns `Fx<CallbackResult, AuthError>` composed via `Fx.gen`.\n */\n/** @internal */\nexport function handleOAuthCallback(\n  providerId: string,\n  arcticProvider: any,\n  oauthConfig: OAuthProviderConfigLike,\n  params: Record<string, string>,\n  cookies: Record<string, string | undefined>,\n): Fx<CallbackResult, AuthError> {\n  return Fx.gen(function* () {\n    const resCookies: OAuthCookie[] = [];\n\n    // 1. Validate state\n    const stateCookieName = oauthCookieName(\"state\", providerId);\n    const storedState = cookies[stateCookieName];\n    const returnedState = params.state;\n\n    yield* Fx.guard(\n      !storedState || !returnedState || storedState !== returnedState,\n      Fx.fail(new AuthError(\"OAUTH_INVALID_STATE\")),\n    );\n    resCookies.push(clearCookie(\"state\", providerId));\n\n    // Check for error from provider\n    if (params.error) {\n      const cause = {\n        providerId,\n        error: params.error,\n        error_description: params.error_description,\n      };\n      logWithLevel(\"DEBUG\", \"OAuthCallbackError\", cause);\n      yield* Fx.fail(\n        new AuthError(\n          \"OAUTH_PROVIDER_ERROR\",\n          \"OAuth provider returned an error\",\n          {\n            cause: JSON.stringify(cause),\n          },\n        ),\n      );\n    }\n\n    // 2. Get code\n    const code = yield* params.code != null\n      ? Fx.succeed(params.code)\n      : Fx.fail(\n          new AuthError(\n            \"OAUTH_PROVIDER_ERROR\",\n            \"Missing authorization code in callback\",\n          ),\n        );\n\n    // 3. Read PKCE verifier from cookie if applicable\n    let codeVerifier: string | undefined;\n    if (isPKCEProvider(arcticProvider)) {\n      const pkceCookieName = oauthCookieName(\"pkce\", providerId);\n      codeVerifier = yield* cookies[pkceCookieName] != null\n        ? Fx.succeed(cookies[pkceCookieName]!)\n        : Fx.fail(\n            new AuthError(\n              \"OAUTH_MISSING_VERIFIER\",\n              \"Missing PKCE verifier cookie for OAuth callback\",\n            ),\n          );\n      resCookies.push(clearCookie(\"pkce\", providerId));\n    }\n\n    let nonce: string | undefined;\n    if (oauthConfig.nonce === true) {\n      const nonceCookieName = oauthCookieName(\"nonce\", providerId);\n      nonce = yield* cookies[nonceCookieName] != null\n        ? Fx.succeed(cookies[nonceCookieName]!)\n        : Fx.fail(\n            new AuthError(\n              \"OAUTH_PROVIDER_ERROR\",\n              \"Missing nonce cookie for OAuth callback\",\n            ),\n          );\n      resCookies.push(clearCookie(\"nonce\", providerId));\n    }\n\n    // 4. Exchange code for tokens\n    const tokens = yield* exchangeCode(arcticProvider, code, codeVerifier);\n\n    if (oauthConfig.validateTokens !== undefined) {\n      yield* Fx.from({\n        ok: () => oauthConfig.validateTokens!(tokens, { nonce }),\n        err: (e) =>\n          new AuthError(\n            \"OAUTH_PROVIDER_ERROR\",\n            `Token validation failed: ${e instanceof Error ? e.message : String(e)}`,\n          ),\n      });\n    }\n\n    // 5. Extract profile\n    const rawProfile = yield* extractProfile(providerId, oauthConfig, tokens);\n    const profile = yield* validateProfileId(providerId, rawProfile);\n\n    logWithLevel(\"DEBUG\", \"OAuth callback profile extracted\", {\n      providerId,\n      profileId: profile.id,\n    });\n\n    // 6. Compute signature for verifier validation\n    const state = storedState!;\n    const signature = getAuthorizationSignature({ codeVerifier, state });\n\n    return {\n      profile,\n      providerAccountId: profile.id,\n      cookies: resCookies,\n      signature,\n    };\n  });\n}\n"],"mappings":"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"}
+{"version":3,"file":"oauth.js","names":[],"sources":["../../src/server/oauth.ts"],"sourcesContent":["/**\n * Arctic-based OAuth flow implementation.\n *\n * Uses Arctic for OAuth provider integration.\n *\n * All functions return `Fx<A, ConvexError<any>>` composed via `Fx.gen` pipelines.\n *\n * @internal\n * @module\n */\n\nimport { Fx } from \"@robelest/fx\";\nimport { Cv } from \"@robelest/fx/convex\";\nimport * as arctic from \"arctic\";\nimport type { ConvexError } from \"convex/values\";\n\nimport { SHARED_COOKIE_OPTIONS } from \"./cookies\";\nimport type { OAuthProfile } from \"./types\";\nimport { logWithLevel } from \"./utils\";\nimport { isLocalHost } from \"./utils\";\n\ntype OAuthProviderConfigLike = {\n  scopes?: string[];\n  profile?: (tokens: arctic.OAuth2Tokens) => Promise<OAuthProfile>;\n  nonce?: boolean;\n  validateTokens?: (\n    tokens: arctic.OAuth2Tokens,\n    ctx: { nonce?: string },\n  ) => Promise<void>;\n};\n\n// ============================================================================\n// Types\n// ============================================================================\n\n/** A cookie to be set on the HTTP response. */\n/** @internal */\nexport interface OAuthCookie {\n  name: string;\n  value: string;\n  options: Record<string, unknown>;\n}\n\n/** Result of creating an authorization URL. */\n/** @internal */\nexport interface AuthorizationResult {\n  redirect: string;\n  cookies: OAuthCookie[];\n  signature: string;\n}\n\n/** Result of handling an OAuth callback. */\n/** @internal */\nexport interface CallbackResult {\n  profile: OAuthProfile;\n  providerAccountId: string;\n  cookies: OAuthCookie[];\n  signature: string;\n}\n\n// ============================================================================\n// Cookie helpers\n// ============================================================================\n\nconst COOKIE_TTL = 60 * 15; // 15 minutes\n\nfunction oauthCookieName(type: \"state\" | \"pkce\" | \"nonce\", providerId: string) {\n  const prefix = !isLocalHost(process.env.CONVEX_SITE_URL) ? \"__Host-\" : \"\";\n  return prefix + providerId + \"OAuth\" + type;\n}\n\nfunction createCookie(\n  type: \"state\" | \"pkce\" | \"nonce\",\n  providerId: string,\n  value: string,\n): OAuthCookie {\n  const expires = new Date();\n  expires.setTime(expires.getTime() + COOKIE_TTL * 1000);\n  return {\n    name: oauthCookieName(type, providerId),\n    value,\n    options: { ...SHARED_COOKIE_OPTIONS, expires },\n  };\n}\n\nfunction clearCookie(\n  type: \"state\" | \"pkce\" | \"nonce\",\n  providerId: string,\n): OAuthCookie {\n  return {\n    name: oauthCookieName(type, providerId),\n    value: \"\",\n    options: { ...SHARED_COOKIE_OPTIONS, maxAge: 0 },\n  };\n}\n\n// ============================================================================\n// Signature (ConvexAuth-specific verifier mechanism)\n// ============================================================================\n\n/**\n * Creates a signature string from the OAuth state parameters.\n * This is stored in the verifier table and validated during callback.\n */\n/** @internal */\nexport function getAuthorizationSignature({\n  codeVerifier,\n  state,\n}: {\n  codeVerifier?: string;\n  state?: string;\n}) {\n  return [codeVerifier, state].filter((param) => param !== undefined).join(\" \");\n}\n\n// ============================================================================\n// PKCE Detection\n// ============================================================================\n\n/**\n * Detect whether an Arctic provider uses PKCE by checking the arity\n * of `createAuthorizationURL`. PKCE providers take 3 args\n * (state, codeVerifier, scopes), non-PKCE take 2 (state, scopes).\n */\nfunction isPKCEProvider(provider: any): boolean {\n  return (\n    typeof provider.createAuthorizationURL === \"function\" &&\n    provider.createAuthorizationURL.length >= 3\n  );\n}\n\n// ============================================================================\n// Token exchange — wraps Arctic's validateAuthorizationCode\n// ============================================================================\n\n/**\n * Exchange the authorization code for tokens via Arctic.\n * Maps Arctic-specific errors to typed `ConvexError<any>` failures.\n */\nfunction exchangeCode(\n  arcticProvider: any,\n  code: string,\n  codeVerifier: string | undefined,\n): Fx<arctic.OAuth2Tokens, ConvexError<any>> {\n  return Fx.from({\n    ok: () =>\n      isPKCEProvider(arcticProvider)\n        ? arcticProvider.validateAuthorizationCode(code, codeVerifier)\n        : arcticProvider.validateAuthorizationCode(code),\n    err: (e) => {\n      if (e instanceof arctic.OAuth2RequestError) {\n        return Cv.error({\n          code: \"OAUTH_PROVIDER_ERROR\",\n          message: `Token exchange failed: ${e.code}`,\n        });\n      }\n      if (e instanceof arctic.ArcticFetchError) {\n        return Cv.error({\n          code: \"OAUTH_PROVIDER_ERROR\",\n          message: `Network error during token exchange: ${e.message}`,\n        });\n      }\n      // Unknown error — treat as unrecoverable defect; we surface it as\n      // an ConvexError<any> here so the pipeline type stays Fx<_, ConvexError<any>>.\n      // The original `throw e` re-throw is replicated via Fx.fatal below.\n      return Cv.error({\n        code: \"OAUTH_PROVIDER_ERROR\",\n        message: `Unexpected error during token exchange: ${e instanceof Error ? e.message : String(e)}`,\n      });\n    },\n  }).pipe(\n    Fx.chain((tokens) => {\n      // If the original error was neither OAuth2RequestError nor\n      // ArcticFetchError the old code re-threw it raw. We replicate that\n      // by checking whether we created an \"Unexpected\" marker message\n      // — but since `Fx.from` already mapped it, we just pass through.\n      return Fx.succeed(tokens);\n    }),\n  );\n}\n\n/**\n * Extract the user profile from tokens using the config callback,\n * OIDC auto-decode, or fail if neither is available.\n */\nfunction extractProfile(\n  providerId: string,\n  oauthConfig: OAuthProviderConfigLike,\n  tokens: arctic.OAuth2Tokens,\n): Fx<OAuthProfile, ConvexError<any>> {\n  const hasIdToken =\n    \"id_token\" in tokens.data &&\n    typeof (tokens.data as any).id_token === \"string\";\n  const profileSource = oauthConfig.profile\n    ? { source: \"callback\" as const }\n    : hasIdToken\n      ? { source: \"idToken\" as const }\n      : { source: \"missing\" as const };\n\n  return Fx.match(profileSource, profileSource.source, {\n    callback: (_profileSource) =>\n      Fx.from({\n        ok: () => oauthConfig.profile!(tokens),\n        err: (e) =>\n          Cv.error({\n            code: \"OAUTH_INVALID_PROFILE\",\n            message: `Profile callback threw: ${e instanceof Error ? e.message : String(e)}`,\n          }),\n      }),\n    idToken: (_profileSource) => {\n      const claims = arctic.decodeIdToken(tokens.idToken()) as Record<\n        string,\n        unknown\n      >;\n      return Fx.succeed({\n        id: (claims.sub as string) ?? crypto.randomUUID(),\n        name: (claims.name as string) ?? undefined,\n        email: (claims.email as string) ?? undefined,\n        image: (claims.picture as string) ?? undefined,\n      });\n    },\n    missing: (_profileSource) =>\n      Cv.fail({\n        code: \"OAUTH_INVALID_PROFILE\",\n        message:\n          `Provider \"${providerId}\" does not return an ID token. ` +\n          `Add a \\`profile\\` callback in the OAuth() config to extract user info from the access token.`,\n      }),\n  });\n}\n\n/**\n * Validate that the profile has a non-empty string `id`.\n */\nfunction validateProfileId(\n  providerId: string,\n  profile: OAuthProfile,\n): Fx<OAuthProfile, ConvexError<any>> {\n  return typeof profile.id === \"string\" && profile.id\n    ? Fx.succeed(profile)\n    : Cv.fail({\n        code: \"OAUTH_INVALID_PROFILE\",\n        message: `The profile callback for \"${providerId}\" must return an object with a string \\`id\\` field.`,\n      });\n}\n\n// ============================================================================\n// Authorization URL creation\n// ============================================================================\n\n/**\n * Create an OAuth authorization URL using an Arctic provider.\n *\n * Handles PKCE detection, state generation, and cookie creation.\n */\n/** @internal */\nexport async function createOAuthAuthorizationURL(\n  providerId: string,\n  arcticProvider: any,\n  oauthConfig: OAuthProviderConfigLike,\n): Promise<AuthorizationResult> {\n  const state = arctic.generateState();\n  const cookies: OAuthCookie[] = [];\n  let codeVerifier: string | undefined;\n\n  const scopes = oauthConfig.scopes ?? [];\n\n  let url: URL;\n\n  if (isPKCEProvider(arcticProvider)) {\n    codeVerifier = arctic.generateCodeVerifier();\n    url = arcticProvider.createAuthorizationURL(state, codeVerifier, scopes);\n    cookies.push(createCookie(\"pkce\", providerId, codeVerifier));\n  } else {\n    url = arcticProvider.createAuthorizationURL(state, scopes);\n  }\n\n  cookies.push(createCookie(\"state\", providerId, state));\n\n  if (oauthConfig.nonce === true) {\n    const nonce = arctic.generateState();\n    url.searchParams.set(\"nonce\", nonce);\n    cookies.push(createCookie(\"nonce\", providerId, nonce));\n  }\n\n  logWithLevel(\"DEBUG\", \"OAuth authorization URL created\", {\n    url: url.toString(),\n    providerId,\n    hasPKCE: !!codeVerifier,\n  });\n\n  const signature = getAuthorizationSignature({ codeVerifier, state });\n\n  return {\n    redirect: url.toString(),\n    cookies,\n    signature,\n  };\n}\n\n// ============================================================================\n// OAuth callback handling\n// ============================================================================\n\n/**\n * Handle the OAuth callback: validate state, exchange code for tokens,\n * extract profile.\n *\n * Returns `Fx<CallbackResult, ConvexError<any>>` composed via `Fx.gen`.\n */\n/** @internal */\nexport function handleOAuthCallback(\n  providerId: string,\n  arcticProvider: any,\n  oauthConfig: OAuthProviderConfigLike,\n  params: Record<string, string>,\n  cookies: Record<string, string | undefined>,\n): Fx<CallbackResult, ConvexError<any>> {\n  return Fx.gen(function* () {\n    const resCookies: OAuthCookie[] = [];\n\n    // 1. Validate state\n    const stateCookieName = oauthCookieName(\"state\", providerId);\n    const storedState = cookies[stateCookieName];\n    const returnedState = params.state;\n\n    yield* Fx.guard(\n      !storedState || !returnedState || storedState !== returnedState,\n      Cv.fail({\n        code: \"OAUTH_INVALID_STATE\",\n        message: \"Invalid OAuth state. Please try signing in again.\",\n      }),\n    );\n    resCookies.push(clearCookie(\"state\", providerId));\n\n    // Check for error from provider\n    if (params.error) {\n      const cause = {\n        providerId,\n        error: params.error,\n        error_description: params.error_description,\n      };\n      logWithLevel(\"DEBUG\", \"OAuthCallbackError\", cause);\n      yield* Cv.fail({\n        code: \"OAUTH_PROVIDER_ERROR\",\n        message: \"OAuth provider returned an error\",\n        cause: JSON.stringify(cause),\n      });\n    }\n\n    // 2. Get code\n    const code = yield* params.code != null\n      ? Fx.succeed(params.code)\n      : Cv.fail({\n          code: \"OAUTH_PROVIDER_ERROR\",\n          message: \"Missing authorization code in callback\",\n        });\n\n    // 3. Read PKCE verifier from cookie if applicable\n    let codeVerifier: string | undefined;\n    if (isPKCEProvider(arcticProvider)) {\n      const pkceCookieName = oauthCookieName(\"pkce\", providerId);\n      codeVerifier = yield* cookies[pkceCookieName] != null\n        ? Fx.succeed(cookies[pkceCookieName]!)\n        : Cv.fail({\n            code: \"OAUTH_MISSING_VERIFIER\",\n            message: \"Missing PKCE verifier cookie for OAuth callback\",\n          });\n      resCookies.push(clearCookie(\"pkce\", providerId));\n    }\n\n    let nonce: string | undefined;\n    if (oauthConfig.nonce === true) {\n      const nonceCookieName = oauthCookieName(\"nonce\", providerId);\n      nonce = yield* cookies[nonceCookieName] != null\n        ? Fx.succeed(cookies[nonceCookieName]!)\n        : Cv.fail({\n            code: \"OAUTH_PROVIDER_ERROR\",\n            message: \"Missing nonce cookie for OAuth callback\",\n          });\n      resCookies.push(clearCookie(\"nonce\", providerId));\n    }\n\n    // 4. Exchange code for tokens\n    const tokens = yield* exchangeCode(arcticProvider, code, codeVerifier);\n\n    if (oauthConfig.validateTokens !== undefined) {\n      yield* Fx.from({\n        ok: () => oauthConfig.validateTokens!(tokens, { nonce }),\n        err: (e) =>\n          Cv.error({\n            code: \"OAUTH_PROVIDER_ERROR\",\n            message: `Token validation failed: ${e instanceof Error ? e.message : String(e)}`,\n          }),\n      });\n    }\n\n    // 5. Extract profile\n    const rawProfile = yield* extractProfile(providerId, oauthConfig, tokens);\n    const profile = yield* validateProfileId(providerId, rawProfile);\n\n    logWithLevel(\"DEBUG\", \"OAuth callback profile extracted\", {\n      providerId,\n      profileId: profile.id,\n    });\n\n    // 6. Compute signature for verifier validation\n    const state = storedState!;\n    const signature = getAuthorizationSignature({ codeVerifier, state });\n\n    return {\n      profile,\n      providerAccountId: profile.id,\n      cookies: resCookies,\n      signature,\n    };\n  });\n}\n"],"mappings":"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"}

package/dist/server/passkey.d.ts

@@ -1,6 +1,6 @@
 import { AuthDataModel, GenericActionCtxWithAuthConfig, PasskeyProviderConfig, SessionInfo } from "./types.js";
-import { AuthError } from "./authError.js";
 import { Fx } from "@robelest/fx";
+import { ConvexError } from "convex/values";
 
 //#region src/server/passkey.d.ts
 type EnrichedActionCtx = GenericActionCtxWithAuthConfig<AuthDataModel>;
@@ -21,7 +21,7 @@ type PasskeyResult = {
 declare function handlePasskeyFx(ctx: EnrichedActionCtx, provider: PasskeyProviderConfig, args: {
   params?: Record<string, any>;
   verifier?: string;
-}): Fx<PasskeyResult, AuthError>;
+}): Fx<PasskeyResult, ConvexError<any>>;
 //#endregion
 export { handlePasskeyFx };
 //# sourceMappingURL=passkey.d.ts.map

package/dist/server/passkey.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"passkey.d.ts","names":[],"sources":["../../src/server/passkey.ts"],"mappings":";;;;;KAmEK,iBAAA,GAAoB,8BAAA,CAA+B,aAAA;;KAoKnD,aAAA;EACC,IAAA;EAAkB,QAAA,EAAU,WAAA;AAAA;EAC5B,IAAA;EAAwB,OAAA,EAAS,MAAA;EAAqB,QAAA;AAAA;;;;;;iBAgD5C,eAAA,CACd,GAAA,EAAK,iBAAA,EACL,QAAA,EAAU,qBAAA,EACV,IAAA;EACE,MAAA,GAAS,MAAA;EACT,QAAA;AAAA,IAED,EAAA,CAAO,aAAA,EAAe,SAAA"}
+{"version":3,"file":"passkey.d.ts","names":[],"sources":["../../src/server/passkey.ts"],"mappings":";;;;;KAmEK,iBAAA,GAAoB,8BAAA,CAA+B,aAAA;;KAqLnD,aAAA;EACC,IAAA;EAAkB,QAAA,EAAU,WAAA;AAAA;EAC5B,IAAA;EAAwB,OAAA,EAAS,MAAA;EAAqB,QAAA;AAAA;;;;;;iBAkD5C,eAAA,CACd,GAAA,EAAK,iBAAA,EACL,QAAA,EAAU,qBAAA,EACV,IAAA;EACE,MAAA,GAAS,MAAA;EACT,QAAA;AAAA,IAED,EAAA,CAAO,aAAA,EAAe,WAAA"}

package/dist/server/passkey.js

@@ -1,4 +1,3 @@
-import { AuthError } from "./authError.js";
 import { userIdFromIdentitySubject } from "./identity.js";
 import { authDb } from "./db.js";
 import { callVerifierSignature } from "./mutations/signature.js";
@@ -6,6 +5,7 @@ import { callSignIn } from "./mutations/signin.js";
 import { callVerifier } from "./mutations/verifier.js";
 import { mutatePasskeyInsert, mutatePasskeyUpdateCounter, mutateVerifierDelete, queryPasskeyByCredentialId, queryPasskeysByUserId, queryUserById, queryUserByVerifiedEmail, queryVerifierById } from "./types.js";
 import { Fx } from "@robelest/fx";
+import { Cv } from "@robelest/fx/convex";
 import { sha256 } from "@oslojs/crypto/sha2";
 import { decodeBase64urlIgnorePadding, encodeBase64urlNoPadding } from "@oslojs/encoding";
 import { decodePKIXECDSASignature, decodeSEC1PublicKey, p256, verifyECDSASignature } from "@oslojs/crypto/ecdsa";
@@ -25,14 +25,14 @@ import { COSEKeyType, ClientDataType, coseAlgorithmES256, coseAlgorithmRS256, cr
 * Uses `@oslojs/webauthn` for attestation/assertion parsing and
 * `@oslojs/crypto` for signature verification.
 *
-* All functions return `Fx<A, AuthError>` composed via `Fx.chain` pipelines.
+* All functions return `Fx<A, ConvexError<any>>` composed via `Fx.chain` pipelines.
 *
 * @module
 */
 /**
 * Resolve passkey relying party options from provider config and environment.
 *
-* Returns `Fx<RpOptions, AuthError>` — fails if neither SITE_URL nor rpId
+* Returns `Fx<RpOptions, ConvexError<any>>` — fails if neither SITE_URL nor rpId
 * is configured.
 */
 const resolveRpOptionsFx = (provider) => {
@@ -43,7 +43,10 @@ const resolveRpOptionsFx = (provider) => {
 		siteUrl,
 		hasSiteUrl,
 		hasRpId
-	}).pipe(Fx.chain(({ siteUrl: siteUrl$1, hasSiteUrl: hasSiteUrl$1, hasRpId: hasRpId$1 }) => !hasSiteUrl$1 && !hasRpId$1 ? Fx.fail(new AuthError("PASSKEY_MISSING_CONFIG", "Passkey provider requires SITE_URL env var (your frontend URL) or explicit rpId / origin in the provider config. CONVEX_SITE_URL cannot be used because WebAuthn RP ID must match the frontend domain.")) : Fx.succeed(siteUrl$1)), Fx.map((siteUrl$1) => {
+	}).pipe(Fx.chain(({ siteUrl: siteUrl$1, hasSiteUrl: hasSiteUrl$1, hasRpId: hasRpId$1 }) => !hasSiteUrl$1 && !hasRpId$1 ? Cv.fail({
+		code: "PASSKEY_MISSING_CONFIG",
+		message: "Passkey provider requires SITE_URL env var (your frontend URL) or explicit rpId / origin in the provider config. CONVEX_SITE_URL cannot be used because WebAuthn RP ID must match the frontend domain."
+	}) : Fx.succeed(siteUrl$1)), Fx.map((siteUrl$1) => {
 		const siteHostname = siteUrl$1 ? new URL(siteUrl$1).hostname : void 0;
 		return {
 			rpName: provider.options.rpName ?? siteHostname ?? "localhost",
@@ -59,27 +62,51 @@ const resolveRpOptionsFx = (provider) => {
 	}));
 };
 /** Verify client data type matches expected WebAuthn ceremony type. */
-const verifyClientDataType = (expectedType, label) => (clientData) => clientData.type === expectedType ? Fx.succeed(clientData) : Fx.fail(new AuthError("PASSKEY_INVALID_CLIENT_DATA", `Invalid client data type: expected ${label}`));
+const verifyClientDataType = (expectedType, label) => (clientData) => clientData.type === expectedType ? Fx.succeed(clientData) : Cv.fail({
+	code: "PASSKEY_INVALID_CLIENT_DATA",
+	message: `Invalid client data type: expected ${label}`
+});
 /** Verify origin is in the allowed list. */
 const verifyOrigin = (rp) => (clientData) => {
 	const allowed = Array.isArray(rp.origin) ? rp.origin : [rp.origin];
-	return allowed.includes(clientData.origin) ? Fx.succeed(clientData) : Fx.fail(new AuthError("PASSKEY_INVALID_ORIGIN", `Invalid origin: ${clientData.origin}, expected one of: ${allowed.join(", ")}`));
+	return allowed.includes(clientData.origin) ? Fx.succeed(clientData) : Cv.fail({
+		code: "PASSKEY_INVALID_ORIGIN",
+		message: `Invalid origin: ${clientData.origin}, expected one of: ${allowed.join(", ")}`
+	});
 };
 /** Verify the challenge hash matches the stored verifier, then delete verifier. */
 const verifyAndConsumeChallenge = (ctx, verifierValue) => (clientData) => {
 	const challengeHash = encodeBase64urlNoPadding(new Uint8Array(sha256(clientData.challenge)));
 	return Fx.from({
 		ok: () => queryVerifierById(ctx, verifierValue),
-		err: () => new AuthError("PASSKEY_INVALID_CHALLENGE")
-	}).pipe(Fx.chain((doc) => !doc || doc.signature !== challengeHash ? Fx.fail(new AuthError("PASSKEY_INVALID_CHALLENGE")) : Fx.succeed(doc)), Fx.chain(() => Fx.from({
+		err: () => Cv.error({
+			code: "PASSKEY_INVALID_CHALLENGE",
+			message: "Invalid or expired passkey challenge."
+		})
+	}).pipe(Fx.chain((doc) => !doc || doc.signature !== challengeHash ? Cv.fail({
+		code: "PASSKEY_INVALID_CHALLENGE",
+		message: "Invalid or expired passkey challenge."
+	}) : Fx.succeed(doc)), Fx.chain(() => Fx.from({
 		ok: () => mutateVerifierDelete(ctx, verifierValue),
-		err: () => new AuthError("PASSKEY_INVALID_CHALLENGE")
+		err: () => Cv.error({
+			code: "PASSKEY_INVALID_CHALLENGE",
+			message: "Invalid or expired passkey challenge."
+		})
 	})), Fx.map(() => clientData));
 };
 /** Verify RP ID hash matches. */
-const verifyRpId = (rpId) => (authData) => authData.verifyRelyingPartyIdHash(rpId) ? Fx.succeed(authData) : Fx.fail(new AuthError("PASSKEY_RP_MISMATCH"));
+const verifyRpId = (rpId) => (authData) => authData.verifyRelyingPartyIdHash(rpId) ? Fx.succeed(authData) : Cv.fail({
+	code: "PASSKEY_RP_MISMATCH",
+	message: "Relying party ID mismatch."
+});
 /** Verify user presence and (optionally) user verification flags. */
-const verifyUserFlags = (rp) => (authData) => !authData.userPresent ? Fx.fail(new AuthError("PASSKEY_USER_PRESENCE")) : rp.userVerification === "required" && !authData.userVerified ? Fx.fail(new AuthError("PASSKEY_USER_VERIFICATION")) : Fx.succeed(authData);
+const verifyUserFlags = (rp) => (authData) => !authData.userPresent ? Cv.fail({
+	code: "PASSKEY_USER_PRESENCE",
+	message: "User presence flag not set."
+}) : rp.userVerification === "required" && !authData.userVerified ? Cv.fail({
+	code: "PASSKEY_USER_VERIFICATION",
+	message: "User verification required but not performed."
+}) : Fx.succeed(authData);
 const PASSKEY_FLOW = {
 	registerOptions: "registerOptions",
 	registerVerify: "registerVerify",
@@ -94,9 +121,15 @@ const PASSKEY_FLOWS = [
 ];
 const resolvePasskeyDispatchFx = (params) => {
 	const flow = params.flow;
-	return typeof flow === "string" && PASSKEY_FLOWS.includes(flow) ? Fx.succeed({ flow }) : Fx.fail(new AuthError("PASSKEY_MISSING_FLOW", "Missing `flow` parameter. Expected one of: registerOptions, registerVerify, authOptions, authVerify"));
+	return typeof flow === "string" && PASSKEY_FLOWS.includes(flow) ? Fx.succeed({ flow }) : Cv.fail({
+		code: "PASSKEY_MISSING_FLOW",
+		message: "Missing `flow` parameter. Expected one of: registerOptions, registerVerify, authOptions, authVerify"
+	});
 };
-const requirePasskeyVerifierFx = (verifier) => verifier != null ? Fx.succeed(verifier) : Fx.fail(new AuthError("PASSKEY_MISSING_VERIFIER"));
+const requirePasskeyVerifierFx = (verifier) => verifier != null ? Fx.succeed(verifier) : Cv.fail({
+	code: "PASSKEY_MISSING_VERIFIER",
+	message: "Missing verifier for passkey operation."
+});
 /**
 * Main passkey handler dispatched from signIn.ts.
 *
@@ -108,8 +141,14 @@ function handlePasskeyFx(ctx, provider, args) {
 		return Fx.match(dispatch).on("flow", {
 			registerOptions: (_) => Fx.zip(Fx.from({
 				ok: () => ctx.auth.getUserIdentity(),
-				err: () => new AuthError("PASSKEY_AUTH_REQUIRED")
-			}).pipe(Fx.chain((id) => id === null ? Fx.fail(new AuthError("PASSKEY_AUTH_REQUIRED")) : Fx.succeed(userIdFromIdentitySubject(id.subject)))), resolveRpOptionsFx(provider)).pipe(Fx.chain(([userId, rp]) => {
+				err: () => Cv.error({
+					code: "PASSKEY_AUTH_REQUIRED",
+					message: "Sign in first, then add a passkey to your account."
+				})
+			}).pipe(Fx.chain((id) => id === null ? Cv.fail({
+				code: "PASSKEY_AUTH_REQUIRED",
+				message: "Sign in first, then add a passkey to your account."
+			}) : Fx.succeed(userIdFromIdentitySubject(id.subject)))), resolveRpOptionsFx(provider)).pipe(Fx.chain(([userId, rp]) => {
 				const challenge = new Uint8Array(32);
 				crypto.getRandomValues(challenge);
 				const challengeHash = encodeBase64urlNoPadding(new Uint8Array(sha256(challenge)));
@@ -158,18 +197,30 @@ function handlePasskeyFx(ctx, provider, args) {
 							verifier
 						};
 					},
-					err: () => new AuthError("INTERNAL_ERROR")
+					err: () => Cv.error({
+						code: "INTERNAL_ERROR",
+						message: "An unexpected error occurred."
+					})
 				});
 			})),
 			registerVerify: (_) => Fx.zip(Fx.from({
 				ok: () => ctx.auth.getUserIdentity(),
-				err: () => new AuthError("PASSKEY_AUTH_REQUIRED")
-			}).pipe(Fx.chain((id) => id === null ? Fx.fail(new AuthError("PASSKEY_AUTH_REQUIRED")) : Fx.succeed(userIdFromIdentitySubject(id.subject)))), resolveRpOptionsFx(provider)).pipe(Fx.chain(([userId, rp]) => requirePasskeyVerifierFx(args.verifier).pipe(Fx.chain((verifier) => {
+				err: () => Cv.error({
+					code: "PASSKEY_AUTH_REQUIRED",
+					message: "Sign in first, then add a passkey to your account."
+				})
+			}).pipe(Fx.chain((id) => id === null ? Cv.fail({
+				code: "PASSKEY_AUTH_REQUIRED",
+				message: "Sign in first, then add a passkey to your account."
+			}) : Fx.succeed(userIdFromIdentitySubject(id.subject)))), resolveRpOptionsFx(provider)).pipe(Fx.chain(([userId, rp]) => requirePasskeyVerifierFx(args.verifier).pipe(Fx.chain((verifier) => {
 				const clientData = parseClientDataJSON(decodeBase64urlIgnorePadding(params.clientDataJSON));
 				return Fx.succeed(clientData).pipe(Fx.chain(verifyClientDataType(ClientDataType.Create, "webauthn.create")), Fx.chain(verifyOrigin(rp)), Fx.chain(verifyAndConsumeChallenge(ctx, verifier)), Fx.map(() => {
 					return parseAttestationObject(decodeBase64urlIgnorePadding(params.attestationObject)).authenticatorData;
 				})).pipe(Fx.chain(verifyRpId(rp.rpId)), Fx.chain(verifyUserFlags(rp)), Fx.chain((authData) => {
-					if (authData.credential == null) return Fx.fail(new AuthError("PASSKEY_NO_CREDENTIAL"));
+					if (authData.credential == null) return Cv.fail({
+						code: "PASSKEY_NO_CREDENTIAL",
+						message: "No credential in attestation."
+					});
 					return Fx.succeed({
 						authData,
 						credential: authData.credential
@@ -210,7 +261,10 @@ function handlePasskeyFx(ctx, provider, args) {
 							return Fx.succeed(rsaPubKey.encodePKCS1());
 						}
 					}[algorithm];
-					return (handler ? handler() : Fx.fail(new AuthError("PASSKEY_UNSUPPORTED_ALGORITHM", `Unsupported algorithm: ${algorithm}`))).pipe(Fx.chain((publicKeyBytes) => Fx.from({
+					return (handler ? handler() : Cv.fail({
+						code: "PASSKEY_UNSUPPORTED_ALGORITHM",
+						message: `Unsupported algorithm: ${algorithm}`
+					})).pipe(Fx.chain((publicKeyBytes) => Fx.from({
 						ok: async () => {
 							const deviceType = params.deviceType ?? "single-device";
 							const backedUp = params.backedUp ?? false;
@@ -239,7 +293,10 @@ function handlePasskeyFx(ctx, provider, args) {
 								})
 							};
 						},
-						err: () => new AuthError("INTERNAL_ERROR")
+						err: () => Cv.error({
+							code: "INTERNAL_ERROR",
+							message: "An unexpected error occurred."
+						})
 					})));
 				}));
 			})))),
@@ -279,16 +336,28 @@ function handlePasskeyFx(ctx, provider, args) {
 							verifier
 						};
 					},
-					err: () => new AuthError("INTERNAL_ERROR")
+					err: () => Cv.error({
+						code: "INTERNAL_ERROR",
+						message: "An unexpected error occurred."
+					})
 				});
 			})),
 			authVerify: (_) => Fx.zip(resolveRpOptionsFx(provider), requirePasskeyVerifierFx(args.verifier)).pipe(Fx.chain(([rp, verifier]) => {
 				const clientDataJSON = decodeBase64urlIgnorePadding(params.clientDataJSON);
 				const clientData = parseClientDataJSON(clientDataJSON);
-				return Fx.succeed(clientData).pipe(Fx.chain(verifyClientDataType(ClientDataType.Get, "webauthn.get")), Fx.chain(verifyOrigin(rp)), Fx.chain(verifyAndConsumeChallenge(ctx, verifier)), Fx.chain(() => params.credentialId != null ? Fx.succeed(params.credentialId) : Fx.fail(new AuthError("PASSKEY_UNKNOWN_CREDENTIAL", "Missing credential ID")))).pipe(Fx.chain((credentialId) => Fx.from({
+				return Fx.succeed(clientData).pipe(Fx.chain(verifyClientDataType(ClientDataType.Get, "webauthn.get")), Fx.chain(verifyOrigin(rp)), Fx.chain(verifyAndConsumeChallenge(ctx, verifier)), Fx.chain(() => params.credentialId != null ? Fx.succeed(params.credentialId) : Cv.fail({
+					code: "PASSKEY_UNKNOWN_CREDENTIAL",
+					message: "Missing credential ID"
+				}))).pipe(Fx.chain((credentialId) => Fx.from({
 					ok: () => queryPasskeyByCredentialId(ctx, credentialId),
-					err: () => new AuthError("PASSKEY_UNKNOWN_CREDENTIAL")
-				}).pipe(Fx.chain((passkey) => passkey ? Fx.succeed(passkey) : Fx.fail(new AuthError("PASSKEY_UNKNOWN_CREDENTIAL", "Unknown credential"))))), Fx.chain((passkey) => {
+					err: () => Cv.error({
+						code: "PASSKEY_UNKNOWN_CREDENTIAL",
+						message: "Unknown passkey credential."
+					})
+				}).pipe(Fx.chain((passkey) => passkey ? Fx.succeed(passkey) : Cv.fail({
+					code: "PASSKEY_UNKNOWN_CREDENTIAL",
+					message: "Unknown credential"
+				})))), Fx.chain((passkey) => {
 					const authenticatorDataBytes = decodeBase64urlIgnorePadding(params.authenticatorData);
 					const authenticatorData = parseAuthenticatorData(authenticatorDataBytes);
 					const signature = decodeBase64urlIgnorePadding(params.signature);
@@ -297,14 +366,26 @@ function handlePasskeyFx(ctx, provider, args) {
 						const storedPublicKeyBytes = new Uint8Array(passkey.publicKey);
 						const handler = {
 							[coseAlgorithmES256]: () => {
-								return verifyECDSASignature(decodeSEC1PublicKey(p256, storedPublicKeyBytes), messageHash, decodePKIXECDSASignature(signature)) ? Fx.succeed(void 0) : Fx.fail(new AuthError("PASSKEY_INVALID_SIGNATURE"));
+								return verifyECDSASignature(decodeSEC1PublicKey(p256, storedPublicKeyBytes), messageHash, decodePKIXECDSASignature(signature)) ? Fx.succeed(void 0) : Cv.fail({
+									code: "PASSKEY_INVALID_SIGNATURE",
+									message: "Invalid passkey signature."
+								});
 							},
 							[coseAlgorithmRS256]: () => {
-								return verifyRSASSAPKCS1v15Signature(decodePKCS1RSAPublicKey(storedPublicKeyBytes), sha256ObjectIdentifier, messageHash, signature) ? Fx.succeed(void 0) : Fx.fail(new AuthError("PASSKEY_INVALID_SIGNATURE"));
+								return verifyRSASSAPKCS1v15Signature(decodePKCS1RSAPublicKey(storedPublicKeyBytes), sha256ObjectIdentifier, messageHash, signature) ? Fx.succeed(void 0) : Cv.fail({
+									code: "PASSKEY_INVALID_SIGNATURE",
+									message: "Invalid passkey signature."
+								});
 							}
 						}[passkey.algorithm];
-						return handler ? handler() : Fx.fail(new AuthError("PASSKEY_UNSUPPORTED_ALGORITHM", `Unsupported algorithm: ${passkey.algorithm}`));
-					})).pipe(Fx.chain(() => passkey.counter !== 0 && authenticatorData.signatureCounter !== 0 && authenticatorData.signatureCounter <= passkey.counter ? Fx.fail(new AuthError("PASSKEY_COUNTER_ERROR")) : Fx.succeed(authenticatorData))).pipe(Fx.chain(() => Fx.from({
+						return handler ? handler() : Cv.fail({
+							code: "PASSKEY_UNSUPPORTED_ALGORITHM",
+							message: `Unsupported algorithm: ${passkey.algorithm}`
+						});
+					})).pipe(Fx.chain(() => passkey.counter !== 0 && authenticatorData.signatureCounter !== 0 && authenticatorData.signatureCounter <= passkey.counter ? Cv.fail({
+						code: "PASSKEY_COUNTER_ERROR",
+						message: "Authenticator counter did not increase — possible credential cloning detected."
+					}) : Fx.succeed(authenticatorData))).pipe(Fx.chain(() => Fx.from({
 						ok: async () => {
 							await mutatePasskeyUpdateCounter(ctx, passkey._id, authenticatorData.signatureCounter, Date.now());
 							return {
@@ -315,7 +396,10 @@ function handlePasskeyFx(ctx, provider, args) {
 								})
 							};
 						},
-						err: () => new AuthError("INTERNAL_ERROR")
+						err: () => Cv.error({
+							code: "INTERNAL_ERROR",
+							message: "An unexpected error occurred."
+						})
 					})));
 				}));
 			}))