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

package/src/server/errors.ts

@@ -1,290 +0,0 @@
-/**
- * Structured error handling for Convex Auth.
- *
- * Every error thrown by the auth system uses `ConvexError` with a
- * `{ code, message }` payload so clients can distinguish error types
- * and display user-friendly messages.
- *
- * **Consumer API:** Use {@link throwAuthError} to throw structured errors
- * from your own Convex functions (e.g. custom authorization checks).
- *
- * **Internal pattern:** The library itself uses `new AuthError(code)` with
- * the `@robelest/fx` effect system (`Fx.fail(new AuthError(code))`).
- * You do not need to use `AuthError` directly — it is an implementation detail.
- *
- * @module
- */
-
-import { ConvexError } from "convex/values";
-
-// ============================================================================
-// Error code → default message map  (single source of truth)
-// ============================================================================
-
-/**
- * Map of every auth error code to its default human-readable message.
- *
- * Use the keys as the `code` argument to {@link throwAuthError}.
- * Clients can match on these codes for conditional error handling.
- *
- * @example
- * ```ts
- * throwAuthError("NOT_SIGNED_IN");
- * // ConvexError { data: { code: "NOT_SIGNED_IN", message: "You must be signed in..." } }
- * ```
- */
-export const AUTH_ERRORS = {
-  // ---- Configuration ----
-  PROVIDER_NOT_CONFIGURED: "This sign-in method is not available.",
-  EMAIL_CONFIG_REQUIRED:
-    "Email transport is not configured. Configure email in createAuth(...).",
-  MISSING_ENV_VAR: "A required server environment variable is missing.",
-  MISSING_ACTION_CONTEXT: "Action context is required for this operation.",
-  INVALID_PARAMETERS: "The provided parameters are invalid.",
-
-  // ---- Authentication ----
-  NOT_SIGNED_IN: "You must be signed in to perform this action.",
-  INVALID_VERIFICATION_CODE: "Invalid or expired verification code.",
-  INVALID_REFRESH_TOKEN: "Your session has expired. Please sign in again.",
-  AUTH_HANDSHAKE_TIMEOUT:
-    "Sign-in succeeded but authentication confirmation timed out.",
-  AUTH_HANDSHAKE_REJECTED:
-    "Authentication was rejected while confirming the session.",
-  SIGN_IN_MISSING_PARAMS:
-    "Cannot sign in: missing provider, code, or refresh token.",
-  UNSUPPORTED_PROVIDER_TYPE: "This provider type is not supported.",
-  INVALID_REDIRECT: "Invalid redirect URL.",
-
-  // ---- Email / Phone ----
-  EMAIL_SEND_FAILED: "Failed to send verification email. Please try again.",
-
-  // ---- API Keys ----
-  INVALID_API_KEY: "Invalid API key.",
-  API_KEY_REVOKED: "This API key has been revoked.",
-  API_KEY_EXPIRED: "This API key has expired.",
-  API_KEY_RATE_LIMITED: "API key rate limit exceeded. Please try again later.",
-  API_KEY_INVALID_SCOPE: "Invalid scope requested for API key.",
-  KEY_NOT_FOUND: "API key not found.",
-
-  // ---- HTTP Bearer Auth ----
-  MISSING_BEARER_TOKEN: "Missing or malformed Authorization: Bearer header.",
-  SCOPE_CHECK_FAILED: "This API key does not have the required permissions.",
-
-  // ---- OAuth ----
-  OAUTH_MISSING_PROVIDER: "Missing OAuth provider ID.",
-  OAUTH_MISSING_VERIFIER: "Missing sign-in verifier.",
-  OAUTH_INVALID_STATE: "Invalid OAuth state. Please try signing in again.",
-  OAUTH_PROVIDER_ERROR: "The sign-in provider returned an error.",
-  OAUTH_MISSING_ID_TOKEN:
-    "ID token claims are missing from the provider response.",
-  OAUTH_INVALID_PROFILE: "The sign-in provider returned an invalid profile.",
-  OAUTH_UNSUPPORTED_AUTH_METHOD:
-    "Unsupported OAuth client authentication method.",
-  OAUTH_NO_USERINFO: "No userinfo endpoint configured for this provider.",
-
-  // ---- Credentials ----
-  ACCOUNT_ALREADY_EXISTS: "An account with these credentials already exists.",
-  ACCOUNT_NOT_FOUND: "Account not found.",
-  INVALID_CREDENTIALS_PROVIDER:
-    "This provider does not support credential operations.",
-  MISSING_CRYPTO_FUNCTION:
-    "This provider is missing a required cryptographic function.",
-  USER_UPDATE_FAILED: "Could not update the user record.",
-
-  // ---- Verifier ----
-  INVALID_VERIFIER: "Invalid or expired verifier.",
-
-  // ---- Passkey ----
-  PASSKEY_MISSING_CONFIG:
-    "Passkey provider requires SITE_URL or explicit rpId configuration.",
-  PASSKEY_AUTH_REQUIRED: "Sign in first, then add a passkey to your account.",
-  PASSKEY_MISSING_VERIFIER: "Missing verifier for passkey operation.",
-  PASSKEY_INVALID_CLIENT_DATA: "Invalid passkey client data.",
-  PASSKEY_INVALID_ORIGIN: "Passkey origin does not match the expected value.",
-  PASSKEY_INVALID_CHALLENGE: "Invalid or expired passkey challenge.",
-  PASSKEY_RP_MISMATCH: "Relying party ID mismatch.",
-  PASSKEY_USER_PRESENCE: "User presence flag not set.",
-  PASSKEY_USER_VERIFICATION: "User verification required but not performed.",
-  PASSKEY_NO_CREDENTIAL: "No credential in attestation.",
-  PASSKEY_UNSUPPORTED_ALGORITHM: "Unsupported passkey algorithm.",
-  PASSKEY_INVALID_SIGNATURE: "Invalid passkey signature.",
-  PASSKEY_UNKNOWN_CREDENTIAL: "Unknown passkey credential.",
-  PASSKEY_COUNTER_ERROR:
-    "Authenticator counter did not increase — possible credential cloning detected.",
-  PASSKEY_MISSING_FLOW: "Missing passkey flow parameter.",
-  PASSKEY_UNKNOWN_FLOW: "Unknown passkey flow.",
-
-  // ---- TOTP ----
-  TOTP_AUTH_REQUIRED: "Sign in first, then set up two-factor authentication.",
-  TOTP_MISSING_VERIFIER: "Missing verifier for TOTP operation.",
-  TOTP_MISSING_CODE: "Missing TOTP code.",
-  TOTP_MISSING_ID: "Missing TOTP enrollment ID.",
-  TOTP_NOT_FOUND: "TOTP enrollment not found.",
-  TOTP_ALREADY_VERIFIED: "TOTP enrollment is already verified.",
-  TOTP_INVALID_CODE: "Invalid TOTP code.",
-  TOTP_INVALID_VERIFIER: "Invalid or expired TOTP verifier.",
-  TOTP_NO_ENROLLMENT: "No verified TOTP enrollment found.",
-  TOTP_MISSING_FLOW: "Missing TOTP flow parameter.",
-  TOTP_UNKNOWN_FLOW: "Unknown TOTP flow.",
-
-  // ---- Device Authorization (RFC 8628) ----
-  DEVICE_CODE_EXPIRED:
-    "The device code has expired. Please start a new authorization request.",
-  DEVICE_CODE_DENIED: "The authorization request was denied.",
-  DEVICE_AUTHORIZATION_PENDING: "The user has not yet authorized this device.",
-  DEVICE_SLOW_DOWN:
-    "Polling too frequently. Increase the interval between requests.",
-  DEVICE_INVALID_USER_CODE: "Invalid or expired user code.",
-  DEVICE_ALREADY_AUTHORIZED: "This device code has already been authorized.",
-  DEVICE_MISSING_FLOW: "Missing device flow parameter.",
-  DEVICE_UNKNOWN_FLOW: "Unknown device flow.",
-
-  // ---- Invites ----
-  INVITE_EXPIRED: "This invitation has expired.",
-  INVITE_EMAIL_MISMATCH: "This invitation is for a different email.",
-  INVITE_ALREADY_ACCEPTED: "This invitation has already been accepted.",
-  DUPLICATE_INVITE:
-    "A pending invite already exists for this email in this group.",
-  INVITE_NOT_FOUND: "Invite not found.",
-  INVITE_NOT_PENDING: "Cannot accept or revoke invite that is not pending.",
-
-  // ---- Groups / Members ----
-  FORBIDDEN: "Access denied.",
-  NO_ACTIVE_GROUP: "User has no active group set.",
-  DUPLICATE_MEMBERSHIP: "User is already a member of this group.",
-
-  // ---- Enterprise ----
-  ENTERPRISE_ALREADY_EXISTS:
-    "An enterprise record already exists for this group.",
-  ENTERPRISE_DOMAIN_TAKEN:
-    "That domain is already attached to another enterprise.",
-
-  // ---- Internal (should never reach user) ----
-  INTERNAL_ERROR: "An unexpected error occurred.",
-} as const satisfies Record<string, string>;
-
-/** Union of all recognized auth error code strings (keys of {@link AUTH_ERRORS}). */
-export type AuthErrorCode = keyof typeof AUTH_ERRORS;
-
-// ============================================================================
-// Error helpers
-// ============================================================================
-
-/**
- * Throw a structured `ConvexError` with `{ code, message }`.
- *
- * Use this in your own Convex functions (queries, mutations, actions)
- * to throw auth-domain errors that clients can match on by `code`.
- * The library itself uses `AuthError` internally, but consumers
- * should prefer this helper for simplicity.
- *
- * @param code    Machine-readable error code from `AUTH_ERRORS`.
- * @param message Optional override for the default human-readable message.
- * @param context Optional extra fields merged into the error payload.
- *
- * @example
- * ```ts
- * import { throwAuthError } from "@robelest/convex-auth/server";
- *
- * // In a custom mutation:
- * if (!isAdmin) {
- *   throwAuthError("FORBIDDEN");
- * }
- * ```
- *
- * @throws {ConvexError} Always — throws a `ConvexError` with `{ code, message }` payload.
- */
-export function throwAuthError(
-  code: AuthErrorCode,
-  message?: string,
-  context?: Record<string, unknown>,
-): never {
-  throw new ConvexError({
-    code,
-    message: message ?? AUTH_ERRORS[code],
-    ...context,
-  });
-}
-
-/**
- * Type guard: check whether a caught value is a structured auth `ConvexError`.
- *
- * @param error - The caught value (typically from a `catch` block).
- * @returns `true` when `error` is a `ConvexError` with `{ code, message }` data.
- *
- * @example
- * ```ts
- * try { await auth.signIn('email', { email }); }
- * catch (e) {
- *   if (isAuthError(e)) console.log(e.data.code); // "EMAIL_SEND_FAILED"
- * }
- * ```
- */
-export function isAuthError(
-  error: unknown,
-): error is ConvexError<{ code: AuthErrorCode; message: string }> {
-  return (
-    error instanceof ConvexError &&
-    typeof error.data === "object" &&
-    error.data !== null &&
-    "code" in error.data &&
-    "message" in error.data
-  );
-}
-
-/**
- * Extract `{ code, message }` from a caught error.
- *
- * Works for `ConvexError` (from Convex actions), plain `Error`
- * instances, and structured auth errors. Returns `null` when the
- * value is not an error object.
- *
- * @param error - The caught value to parse.
- * @returns `{ code, message }` when extractable, or `null`.
- *   When `code` is `null`, the error is not a structured auth error
- *   but `message` still contains the error text.
- *
- * @example
- * ```ts
- * try {
- *   await auth.signIn("email", { email });
- * } catch (e) {
- *   const err = parseAuthError(e);
- *   if (err?.code === "EMAIL_SEND_FAILED") { ... }
- * }
- * ```
- */
-export function parseAuthError(
-  error: unknown,
-):
-  | { code: AuthErrorCode; message: string }
-  | { code: null; message: string }
-  | null {
-  if (isAuthError(error)) {
-    const { code, message } = error.data as {
-      code: AuthErrorCode;
-      message: string;
-    };
-    return { code, message };
-  }
-  // Recognize the Fx-native AuthError class (has _tag + code)
-  if (
-    error instanceof Error &&
-    "_tag" in error &&
-    (error as any)._tag === "AuthError" &&
-    "code" in error &&
-    typeof (error as any).code === "string"
-  ) {
-    return {
-      code: (error as any).code as AuthErrorCode,
-      message: error.message,
-    };
-  }
-  if (error instanceof ConvexError && typeof error.data === "string") {
-    return { code: null, message: error.data };
-  }
-  if (error instanceof Error) {
-    return { code: null, message: error.message };
-  }
-  return null;
-}