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

package/src/server/totp.ts

@@ -10,10 +10,10 @@
 import { encodeBase32LowerCaseNoPadding } from "@oslojs/encoding";
 import { verifyTOTPWithGracePeriod, createTOTPKeyURI } from "@oslojs/otp";
 import type { Fx as FxType } from "@robelest/fx";
-
 import { Fx } from "@robelest/fx";
+import { Cv } from "@robelest/fx/convex";
+import type { ConvexError } from "convex/values";
 
-import { AuthError } from "./authError";
 import { userIdFromIdentitySubject } from "./identity";
 import { callSignIn, callVerifier } from "./mutations/index";
 import { callVerifierSignature } from "./mutations/signature";
@@ -70,43 +70,48 @@ type TotpDispatch =
 
 const resolveTotpFlowFx = (
   params: Record<string, unknown>,
-): FxType<TotpFlow, AuthError> => {
+): FxType<TotpFlow, ConvexError<any>> => {
   const flow = params.flow;
   return typeof flow === "string" && TOTP_FLOWS.includes(flow as never)
     ? Fx.succeed(flow as TotpFlow)
-    : Fx.fail(
-        new AuthError(
-          "TOTP_MISSING_FLOW",
+    : Cv.fail({
+        code: "TOTP_MISSING_FLOW",
+        message:
           "Missing `flow` parameter. Expected one of: setup, confirm, verify",
-        ),
-      );
+      });
 };
 
 const requireTotpVerifierFx = (
   verifier: string | undefined,
-): FxType<string, AuthError> =>
+): FxType<string, ConvexError<any>> =>
   verifier != null
     ? Fx.succeed(verifier)
-    : Fx.fail(new AuthError("TOTP_MISSING_VERIFIER"));
+    : Cv.fail({
+        code: "TOTP_MISSING_VERIFIER",
+        message: "Missing verifier for TOTP operation.",
+      });
 
 const requireTotpCodeFx = (
   params: Record<string, unknown>,
-): FxType<string, AuthError> =>
+): FxType<string, ConvexError<any>> =>
   typeof params.code === "string"
     ? Fx.succeed(params.code)
-    : Fx.fail(new AuthError("TOTP_MISSING_CODE"));
+    : Cv.fail({ code: "TOTP_MISSING_CODE", message: "Missing TOTP code." });
 
 const requireTotpIdFx = (
   params: Record<string, unknown>,
-): FxType<string, AuthError> =>
+): FxType<string, ConvexError<any>> =>
   typeof params.totpId === "string"
     ? Fx.succeed(params.totpId)
-    : Fx.fail(new AuthError("TOTP_MISSING_ID"));
+    : Cv.fail({
+        code: "TOTP_MISSING_ID",
+        message: "Missing TOTP enrollment ID.",
+      });
 
 const resolveTotpDispatchFx = (
   params: Record<string, unknown>,
   verifier: string | undefined,
-): FxType<TotpDispatch, AuthError> =>
+): FxType<TotpDispatch, ConvexError<any>> =>
   resolveTotpFlowFx(params).pipe(
     Fx.chain((flow) =>
       Fx.match({ flow }).on("flow", {
@@ -142,7 +147,7 @@ export const handleTotp = (
   ctx: EnrichedActionCtx,
   provider: TotpProviderConfig,
   args: { params?: Record<string, any>; verifier?: string },
-): FxType<TotpResult, AuthError> => {
+): FxType<TotpResult, ConvexError<any>> => {
   const params = (args.params ?? {}) as Record<string, unknown>;
 
   return resolveTotpDispatchFx(params, args.verifier).pipe(
@@ -151,11 +156,16 @@ export const handleTotp = (
         setup: ({ params }) =>
           Fx.from({
             ok: () => ctx.auth.getUserIdentity(),
-            err: (e) => new AuthError("INTERNAL_ERROR", String(e)),
+            err: (e) =>
+              Cv.error({ code: "INTERNAL_ERROR", message: String(e) }),
           }).pipe(
             Fx.chain((identity) =>
               identity === null
-                ? Fx.fail(new AuthError("TOTP_AUTH_REQUIRED"))
+                ? Cv.fail({
+                    code: "TOTP_AUTH_REQUIRED",
+                    message:
+                      "Sign in first, then set up two-factor authentication.",
+                  })
                 : Fx.succeed(userIdFromIdentitySubject(identity.subject)),
             ),
             Fx.chain((userId) =>
@@ -213,37 +223,52 @@ export const handleTotp = (
                   };
                 },
                 err: (e) =>
-                  new AuthError(
-                    "INTERNAL_ERROR",
-                    `TOTP setup failed: ${String(e)}`,
-                  ),
+                  Cv.error({
+                    code: "INTERNAL_ERROR",
+                    message: `TOTP setup failed: ${String(e)}`,
+                  }),
               }),
             ),
           ),
         confirm: ({ code, totpId, verifier }) =>
           Fx.from({
             ok: () => ctx.auth.getUserIdentity(),
-            err: (e) => new AuthError("INTERNAL_ERROR", String(e)),
+            err: (e) =>
+              Cv.error({ code: "INTERNAL_ERROR", message: String(e) }),
           }).pipe(
             Fx.chain((identity) =>
               identity === null
-                ? Fx.fail(new AuthError("TOTP_AUTH_REQUIRED"))
+                ? Cv.fail({
+                    code: "TOTP_AUTH_REQUIRED",
+                    message:
+                      "Sign in first, then set up two-factor authentication.",
+                  })
                 : Fx.succeed(userIdFromIdentitySubject(identity.subject)),
             ),
             Fx.chain((userId) =>
               Fx.from({
                 ok: () => queryTotpById(ctx, totpId),
-                err: () => new AuthError("TOTP_NOT_FOUND"),
+                err: () =>
+                  Cv.error({
+                    code: "TOTP_NOT_FOUND",
+                    message: "TOTP enrollment not found.",
+                  }),
               })
                 .pipe(
                   Fx.chain((doc) =>
                     doc === null
-                      ? Fx.fail(new AuthError("TOTP_NOT_FOUND"))
+                      ? Cv.fail({
+                          code: "TOTP_NOT_FOUND",
+                          message: "TOTP enrollment not found.",
+                        })
                       : Fx.succeed(doc),
                   ),
                   Fx.chain((totpDoc) =>
                     totpDoc.verified
-                      ? Fx.fail(new AuthError("TOTP_ALREADY_VERIFIED"))
+                      ? Cv.fail({
+                          code: "TOTP_ALREADY_VERIFIED",
+                          message: "TOTP enrollment is already verified.",
+                        })
                       : Fx.succeed(totpDoc),
                   ),
                 )
@@ -257,7 +282,10 @@ export const handleTotp = (
                       30,
                     )
                       ? Fx.succeed(totpDoc)
-                      : Fx.fail(new AuthError("TOTP_INVALID_CODE")),
+                      : Cv.fail({
+                          code: "TOTP_INVALID_CODE",
+                          message: "Invalid TOTP code.",
+                        }),
                   ),
                 )
                 .pipe(
@@ -271,7 +299,11 @@ export const handleTotp = (
                           generateTokens: true,
                         });
                       },
-                      err: (e) => new AuthError("INTERNAL_ERROR", String(e)),
+                      err: (e) =>
+                        Cv.error({
+                          code: "INTERNAL_ERROR",
+                          message: String(e),
+                        }),
                     }),
                   ),
                 )
@@ -286,11 +318,18 @@ export const handleTotp = (
         verify: ({ code, verifier }) =>
           Fx.from({
             ok: () => queryVerifierById(ctx, verifier),
-            err: () => new AuthError("TOTP_INVALID_VERIFIER"),
+            err: () =>
+              Cv.error({
+                code: "TOTP_INVALID_VERIFIER",
+                message: "Invalid or expired TOTP verifier.",
+              }),
           }).pipe(
             Fx.chain((doc) =>
               doc === null
-                ? Fx.fail(new AuthError("TOTP_INVALID_VERIFIER"))
+                ? Cv.fail({
+                    code: "TOTP_INVALID_VERIFIER",
+                    message: "Invalid or expired TOTP verifier.",
+                  })
                 : Fx.succeed(doc),
             ),
             Fx.map((doc) => {
@@ -300,11 +339,18 @@ export const handleTotp = (
             Fx.chain(({ userId, code, verifier }) =>
               Fx.from({
                 ok: () => queryTotpVerifiedByUserId(ctx, userId),
-                err: () => new AuthError("TOTP_NO_ENROLLMENT"),
+                err: () =>
+                  Cv.error({
+                    code: "TOTP_NO_ENROLLMENT",
+                    message: "No verified TOTP enrollment found.",
+                  }),
               }).pipe(
                 Fx.chain((totpDoc) =>
                   totpDoc === null
-                    ? Fx.fail(new AuthError("TOTP_NO_ENROLLMENT"))
+                    ? Cv.fail({
+                        code: "TOTP_NO_ENROLLMENT",
+                        message: "No verified TOTP enrollment found.",
+                      })
                     : Fx.succeed(totpDoc),
                 ),
                 Fx.chain((totpDoc) =>
@@ -316,7 +362,10 @@ export const handleTotp = (
                     30,
                   )
                     ? Fx.succeed(totpDoc)
-                    : Fx.fail(new AuthError("TOTP_INVALID_CODE")),
+                    : Cv.fail({
+                        code: "TOTP_INVALID_CODE",
+                        message: "Invalid TOTP code.",
+                      }),
                 ),
                 Fx.chain((totpDoc) =>
                   Fx.from({
@@ -329,7 +378,8 @@ export const handleTotp = (
                       await mutateVerifierDelete(ctx, verifier);
                       return callSignIn(ctx, { userId, generateTokens: true });
                     },
-                    err: (e) => new AuthError("INTERNAL_ERROR", String(e)),
+                    err: (e) =>
+                      Cv.error({ code: "INTERNAL_ERROR", message: String(e) }),
                   }),
                 ),
                 Fx.map((signInResult) => ({

package/src/server/types.ts

@@ -795,30 +795,25 @@ export type AuthProviderSignInResult = {
   sessionId: GenericId<"Session">;
 } | null;
 
-/** Arguments for `auth.member.resolve()`. */
-export type AuthMemberResolveArgs = {
+/** Arguments for `auth.member.inspect()`. */
+export type AuthMemberInspectArgs = {
   userId: GenericId<"User">;
   groupId: GenericId<"Group">;
   ancestry?: boolean;
-  roleIds?: string[];
-  grants?: string[];
   maxDepth?: number;
 };
 
-/** Result of `auth.member.resolve()` — membership check with role and grant details. */
-export type AuthMemberResolveResult = {
-  ok: boolean;
+/** Result of `auth.member.inspect()` — membership state and derived access details. */
+export type AuthMemberInspectResult = {
   membership: GenericDoc<GenericDataModel, "GroupMember"> | null;
-  matchedGroupId: GenericId<"Group"> | null;
   roleIds: string[];
   grants: string[];
-  missingGrants: string[];
-  depth: number | null;
-  isDirect: boolean;
-  isInherited: boolean;
-  traversedGroupIds: GenericId<"Group">[];
-  code?: "INVALID_ROLE_IDS";
-  invalidRoleIds?: string[];
+};
+
+/** Arguments for `auth.member.require()`. */
+export type AuthMemberRequireArgs = AuthMemberInspectArgs & {
+  roleIds?: string[];
+  grants?: string[];
 };
 
 /**
@@ -846,7 +841,6 @@ export type AuthServerHelpers = {
       ctx: GenericActionCtx<any>,
       args: AuthCreateAccountArgs,
     ) => Promise<{
-      ok: true;
       account: GenericDoc<GenericDataModel, "Account">;
       user: GenericDoc<GenericDataModel, "User">;
     }>;
@@ -860,7 +854,7 @@ export type AuthServerHelpers = {
     update: (
       ctx: GenericActionCtx<any>,
       args: AuthUpdateAccountArgs,
-    ) => Promise<{ ok: true; accountId: GenericId<"Account"> }>;
+    ) => Promise<{ accountId: GenericId<"Account"> }>;
   };
   session: {
     current: (ctx: {
@@ -870,16 +864,19 @@ export type AuthServerHelpers = {
       ctx: GenericActionCtx<any>,
       args: AuthInvalidateSessionsArgs,
     ) => Promise<{
-      ok: true;
       userId: GenericId<"User">;
       except: GenericId<"Session">[];
     }>;
   };
   member: {
-    resolve: (
+    inspect: (
+      ctx: GenericActionCtx<any>,
+      args: AuthMemberInspectArgs,
+    ) => Promise<AuthMemberInspectResult>;
+    require: (
       ctx: GenericActionCtx<any>,
-      args: AuthMemberResolveArgs,
-    ) => Promise<AuthMemberResolveResult>;
+      args: AuthMemberRequireArgs,
+    ) => Promise<AuthMemberInspectResult>;
   };
   provider: {
     signIn: (
@@ -939,7 +936,7 @@ export interface SAMLAttributeMapping {
  * Materialized OAuth provider config (Arctic-based).
  *
  * Carries the Arctic provider instance along with scopes and profile config.
-  * Produced by materializing an `OAuthProviderInstance` during `configDefaults`.
+ * Produced by materializing an `OAuthProviderInstance` during `configDefaults`.
  */
 export interface OAuthMaterializedConfig {
   /**

package/src/server/users.ts

@@ -1,8 +1,8 @@
 import { Fx } from "@robelest/fx";
+import { Cv } from "@robelest/fx/convex";
 import { GenericId } from "convex/values";
 
 import { authDb } from "./db";
-import { AuthError } from "./authError";
 import { Doc, MutationCtx } from "./types";
 import { AuthProviderMaterializedConfig, ConvexAuthConfig } from "./types";
 import { LOG_LEVELS, logWithLevel } from "./utils";
@@ -188,14 +188,15 @@ async function defaultCreateOrUpdateUser(
       Fx.from({
         ok: () => db.users.patch(userId!, userData),
         err: (error) =>
-          new AuthError(
-            "USER_UPDATE_FAILED",
-            `Could not update user document with ID \`${userId}\`, ` +
+          Cv.error({
+            code: "USER_UPDATE_FAILED",
+            message:
+              `Could not update user document with ID \`${userId}\`, ` +
               `either the user has been deleted but their account has not, ` +
               `or the profile data doesn't match the \`users\` table schema: ` +
               `${(error as Error).message}`,
-          ),
-      }).pipe(Fx.recover((e) => Fx.fatal(e.toConvexError()))),
+          }),
+      }).pipe(Fx.recover((e) => Fx.fatal(e))),
     );
   } else {
     userId = (await db.users.insert(userData)) as GenericId<"User">;

package/src/server/utils.ts

@@ -8,24 +8,22 @@ import {
   encodeBase64urlNoPadding,
   encodeHexLowerCase,
 } from "@oslojs/encoding";
-
-import { AuthError } from "./authError";
+import { Cv } from "@robelest/fx/convex";
 
 /**
  * Require an environment variable to be set, throwing at config time if missing.
  *
- * Uses `AuthError.toConvexError()` directly since this is a synchronous guard
+ * Uses `Cv.error()` directly since this is a synchronous guard
  * called inline in many expressions — not suitable for Fx pipeline wrapping.
  */
 /** @internal */
 export function requireEnv(name: string) {
   const value = process.env[name];
   if (value === undefined) {
-    throw new AuthError(
-      "MISSING_ENV_VAR",
-      `Missing environment variable \`${name}\``,
-      { variable: name },
-    ).toConvexError();
+    throw Cv.error({
+      code: "MISSING_ENV_VAR",
+      message: `Missing environment variable \`${name}\``,
+    });
   }
   return value;
 }
@@ -183,10 +181,10 @@ export async function encryptSecret(value: string) {
 export async function decryptSecret(ciphertext: string) {
   const [ivEncoded, payloadEncoded] = ciphertext.split(".");
   if (!ivEncoded || !payloadEncoded) {
-    throw new AuthError(
-      "INVALID_PARAMETERS",
-      "Stored enterprise secret is malformed.",
-    ).toConvexError();
+    throw Cv.error({
+      code: "INVALID_PARAMETERS",
+      message: "Stored enterprise secret is malformed.",
+    });
   }
   const key = await getSecretCryptoKey();
   const decrypted = await crypto.subtle.decrypt(

package/dist/component/server/authError.js

@@ -1,34 +0,0 @@
-import { AUTH_ERRORS } from "./errors.js";
-import { Cv } from "@robelest/fx/convex";
-
-//#region src/server/authError.ts
-/**
-* Typed error for the Fx error channel.
-*
-* Use with `Fx.fail(new AuthError("CODE"))` in pipelines.
-* At Convex boundaries, {@link toConvexError} converts these to `ConvexError`.
-*/
-var AuthError = class extends Error {
-	/**
-	* Discriminant tag for error channel matching.
-	* @readonly
-	*/
-	_tag = "AuthError";
-	constructor(code, message, context) {
-		super(message ?? AUTH_ERRORS[code]);
-		this.code = code;
-		this.context = context;
-	}
-	/** Convert to the `ConvexError` shape the Convex runtime expects. */
-	toConvexError() {
-		return Cv.error({
-			code: this.code,
-			message: this.message,
-			...this.context
-		});
-	}
-};
-
-//#endregion
-export { AuthError };
-//# sourceMappingURL=authError.js.map

package/dist/component/server/authError.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"authError.js","names":[],"sources":["../../../src/server/authError.ts"],"sourcesContent":["import { Cv } from \"@robelest/fx/convex\";\nimport type { ConvexError } from \"convex/values\";\n\nimport { AUTH_ERRORS } from \"./errors\";\nimport type { AuthErrorCode } from \"./errors\";\n\n/**\n * Typed error for the Fx error channel.\n *\n * Use with `Fx.fail(new AuthError(\"CODE\"))` in pipelines.\n * At Convex boundaries, {@link toConvexError} converts these to `ConvexError`.\n */\nexport class AuthError extends Error {\n  /**\n   * Discriminant tag for error channel matching.\n   * @readonly\n   */\n  readonly _tag = \"AuthError\" as const;\n\n  constructor(\n    /**\n     * Machine-readable error code.\n     * @readonly\n     */\n    readonly code: AuthErrorCode,\n    message?: string,\n    /**\n     * Optional structured context for diagnostics.\n     * @readonly\n     */\n    readonly context?: Record<string, unknown>,\n  ) {\n    super(message ?? AUTH_ERRORS[code]);\n  }\n\n  /** Convert to the `ConvexError` shape the Convex runtime expects. */\n  toConvexError(): ConvexError<{ code: AuthErrorCode; message: string }> {\n    return Cv.error({\n      code: this.code,\n      message: this.message,\n      ...this.context,\n    });\n  }\n}\n"],"mappings":";;;;;;;;;;AAYA,IAAa,YAAb,cAA+B,MAAM;;;;;CAKnC,AAAS,OAAO;CAEhB,YAKE,AAAS,MACT,SAKA,AAAS,SACT;AACA,QAAM,WAAW,YAAY,MAAM;EAR1B;EAMA;;;CAMX,gBAAuE;AACrE,SAAO,GAAG,MAAM;GACd,MAAM,KAAK;GACX,SAAS,KAAK;GACd,GAAG,KAAK;GACT,CAAC"}

package/dist/component/server/errors.d.ts

@@ -1 +0,0 @@
-import { ConvexError } from "convex/values";

package/dist/component/server/errors.js

@@ -1,137 +0,0 @@
-import { ConvexError } from "convex/values";
-
-//#region src/server/errors.ts
-/**
-* 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
-*/
-/**
-* 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..." } }
-* ```
-*/
-const AUTH_ERRORS = {
-	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.",
-	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_SEND_FAILED: "Failed to send verification email. Please try again.",
-	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.",
-	MISSING_BEARER_TOKEN: "Missing or malformed Authorization: Bearer header.",
-	SCOPE_CHECK_FAILED: "This API key does not have the required permissions.",
-	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.",
-	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.",
-	INVALID_VERIFIER: "Invalid or expired verifier.",
-	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_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_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.",
-	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.",
-	FORBIDDEN: "Access denied.",
-	NO_ACTIVE_GROUP: "User has no active group set.",
-	DUPLICATE_MEMBERSHIP: "User is already a member of this group.",
-	ENTERPRISE_ALREADY_EXISTS: "An enterprise record already exists for this group.",
-	ENTERPRISE_DOMAIN_TAKEN: "That domain is already attached to another enterprise.",
-	INTERNAL_ERROR: "An unexpected error occurred."
-};
-/**
-* 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"
-* }
-* ```
-*/
-function isAuthError(error) {
-	return error instanceof ConvexError && typeof error.data === "object" && error.data !== null && "code" in error.data && "message" in error.data;
-}
-
-//#endregion
-export { AUTH_ERRORS, isAuthError };
-//# sourceMappingURL=errors.js.map

package/dist/component/server/errors.js.map

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