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

package/src/server/auth.ts

@@ -4,13 +4,12 @@
  * @module
  */
 
+import { Cv } from "@robelest/fx/convex";
 import type { UserIdentity } from "convex/server";
 import type { GenericId } from "convex/values";
 
 import type { AuthApiRefs } from "../client/index";
 import { Auth as AuthFactory } from "./runtime";
-import { Fx } from "@robelest/fx";
-import { AuthError } from "./authError";
 import type { Doc } from "./types";
 import type {
   AuthAuthorizationConfig,
@@ -35,11 +34,14 @@ import type {
  */
 export type AuthConfig = Omit<ConvexAuthConfig, "component">;
 
+/** Canonical user document type exposed by Convex Auth. */
+export type UserDoc = Doc<"User">;
+
 type MemberApiWithAuthorization<
   TAuthorization extends AuthAuthorizationConfig | undefined,
 > = Omit<
   ReturnType<typeof AuthFactory>["auth"]["member"],
-  "create" | "list" | "update" | "resolve"
+  "create" | "list" | "update" | "inspect" | "require"
 > & {
   create: (
     ctx: Parameters<
@@ -52,7 +54,7 @@ type MemberApiWithAuthorization<
       status?: string;
       extend?: Record<string, unknown>;
     },
-  ) => Promise<{ ok: true; memberId: string }>;
+  ) => Promise<{ memberId: string }>;
   list: (
     ctx: Parameters<
       ReturnType<typeof AuthFactory>["auth"]["member"]["list"]
@@ -76,10 +78,21 @@ type MemberApiWithAuthorization<
     >[0],
     memberId: string,
     data: Record<string, unknown> & { roleIds?: AuthRoleId<TAuthorization>[] },
-  ) => Promise<{ ok: true; memberId: string }>;
-  resolve: (
+  ) => Promise<{ memberId: string }>;
+  inspect: (
     ctx: Parameters<
-      ReturnType<typeof AuthFactory>["auth"]["member"]["resolve"]
+      ReturnType<typeof AuthFactory>["auth"]["member"]["inspect"]
+    >[0],
+    opts: {
+      userId: string;
+      groupId: string;
+      ancestry?: boolean;
+      maxDepth?: number;
+    },
+  ) => ReturnType<ReturnType<typeof AuthFactory>["auth"]["member"]["inspect"]>;
+  require: (
+    ctx: Parameters<
+      ReturnType<typeof AuthFactory>["auth"]["member"]["require"]
     >[0],
     opts: {
       userId: string;
@@ -89,10 +102,9 @@ type MemberApiWithAuthorization<
       grants?: AuthGrant<TAuthorization>[];
       maxDepth?: number;
     },
-  ) => ReturnType<ReturnType<typeof AuthFactory>["auth"]["member"]["resolve"]>;
+  ) => ReturnType<ReturnType<typeof AuthFactory>["auth"]["member"]["require"]>;
 };
 
-
 /**
  * The base auth API surface returned by {@link createAuth}.
  *
@@ -124,30 +136,29 @@ export type AuthApiBase<
   key: ReturnType<typeof AuthFactory>["auth"]["key"];
   http: ReturnType<typeof AuthFactory>["auth"]["http"];
   /**
-   * Resolve the current user's auth context. Framework-agnostic — use
+   * Resolve the current request's auth context. Framework-agnostic — use
    * this in fluent-convex middleware, custom wrappers, or anywhere you
-   * need the resolved `{ userId, user, groupId, role, grants }` object.
+   * need the current `{ userId, user, groupId, role, grants }` object.
    *
-   * Returns `null` when unauthenticated. Does not throw.
+   * Throws a structured `ConvexError` when unauthenticated.
    *
    * @param ctx - Convex query, mutation, or action context.
-   * @returns The resolved auth context, or `null`.
+   * @returns The current auth context.
    *
    * @example fluent-convex middleware
    * ```ts
    * const withAuth = convex.createMiddleware(async (ctx, next) => {
-   *   return next({ ...ctx, auth: await auth.resolve(ctx) });
+   *   return next({ ...ctx, auth: await auth.context(ctx) });
    * });
    * ```
    *
    * @example Direct usage in a handler
    * ```ts
-   * const resolved = await auth.resolve(ctx);
-   * if (!resolved) return { ok: false, code: "NOT_SIGNED_IN" };
-   * const { userId, grants } = resolved;
+   * const authContext = await auth.context(ctx);
+   * const { userId, grants } = authContext;
    * ```
    */
-  resolve: (ctx: any) => Promise<AuthResolvedContext | null>;
+  context: (ctx: any) => Promise<AuthContext>;
   /**
    * Context enrichment for convex-helpers `customQuery` / `customMutation` /
    * `customAction`.
@@ -156,9 +167,9 @@ export type AuthApiBase<
    * and grants, then attaches them to `ctx.auth`. Returns a `Customization`
    * object compatible with convex-helpers' custom function builders.
    *
-   * `ctx.auth` is `{ userId, user, groupId, role, grants }` when
-   * authenticated, `null` when unauthenticated. No throwing — your
-   * handler decides how to respond.
+   * `ctx.auth` is the current request auth context.
+   * By default this throws when unauthenticated so handlers can assume
+   * `ctx.auth.userId` and `ctx.auth.user` exist.
    *
    * @returns A convex-helpers `Customization` object.
    *
@@ -180,7 +191,6 @@ export type AuthApiBase<
    * export const list = authQuery({
    *   args: { workspaceId: v.string() },
    *   handler: async (ctx, args) => {
-   *     if (!ctx.auth) return [];
    *     const { userId, groupId, grants } = ctx.auth;
    *     // business logic
    *   },
@@ -190,24 +200,40 @@ export type AuthApiBase<
   ctx: () => {
     args: Record<string, never>;
     input: (ctx: any) => Promise<{
-      ctx: { auth: AuthResolvedContext | null };
+      ctx: { auth: AuthContext };
       args: Record<string, never>;
     }>;
   };
 };
 
 /**
- * Resolved auth context injected into `ctx.auth` by `auth.ctx()`.
+ * Current request auth context injected into `ctx.auth` by `auth.ctx()` and
+ * {@link AuthCtx}. This is the authenticated auth shape returned by
+ * {@link createAuth().context}. Optional context builders may still surface
+ * nullable fields when `optional: true` is used.
  *
- * - `null` when unauthenticated.
  * - `groupId` is `null` when the user has no active group set.
- * - `role` / `grants` are `null` / `[]` when no active group or no membership.
+ * - `role` is `null` when no active group or no membership is resolved.
+ * - `grants` is `[]` when no active group or no membership is resolved.
+ *
+ * @example
+ * ```ts
+ * import type { AuthContext } from "@robelest/convex-auth/server";
+ *
+ * const mockAuth: AuthContext = {
+ *   userId: "user123" as Id<"User">,
+ *   user: { _id: "user123", email: "test@example.com" },
+ *   groupId: "group456",
+ *   role: "admin",
+ *   grants: ["read", "write"],
+ * };
+ * ```
  */
-export type AuthResolvedContext = {
+export type AuthContext = {
   /** The authenticated user's document ID. */
-  userId: string;
+  userId: GenericId<"User">;
   /** The authenticated user's full document. */
-  user: any;
+  user: UserDoc;
   /** The user's active group ID, or `null` if none set. */
   groupId: string | null;
   /** The user's primary role in the active group, or `null`. */
@@ -216,6 +242,20 @@ export type AuthResolvedContext = {
   grants: string[];
 };
 
+type AuthCtxBase = {
+  getUserIdentity: () => Promise<UserIdentity | null>;
+};
+
+type RequiredAuthCtxState = AuthCtxBase & AuthContext;
+
+type OptionalAuthCtxState = AuthCtxBase & {
+  userId: GenericId<"User"> | null;
+  user: UserDoc | null;
+  groupId: string | null;
+  role: string | null;
+  grants: string[];
+};
+
 type InternalSsoApi = ReturnType<typeof AuthFactory>["auth"]["sso"];
 
 type PublicSsoAdminApi = {
@@ -231,7 +271,6 @@ type PublicSsoAdminApi = {
           isPrimary?: boolean;
         }>,
       ) => Promise<{
-        ok: true;
         enterpriseId: string;
         domains: Array<{
           domainId: string;
@@ -246,7 +285,6 @@ type PublicSsoAdminApi = {
           ctx: Parameters<InternalSsoApi["connection"]["create"]>[0],
           args: { enterpriseId: string; domain: string },
         ) => Promise<{
-          ok: true;
           enterpriseId: string;
           domain: string;
           requestedAt: number;
@@ -261,7 +299,6 @@ type PublicSsoAdminApi = {
           ctx: Parameters<InternalSsoApi["connection"]["create"]>[0],
           args: { enterpriseId: string; domain: string },
         ) => Promise<{
-          ok: boolean;
           enterpriseId: string;
           domain: string;
           verifiedAt?: number;
@@ -370,7 +407,7 @@ export type InferClientApi<T> =
     : AuthApiRefs;
 
 /** @internal */
-export type AuthLike = Pick<AuthApiBase, "user">;
+export type AuthLike = Pick<AuthApiBase, "user" | "member">;
 
 // ============================================================================
 // Auth setup APIs
@@ -415,9 +452,12 @@ export type AuthLike = Pick<AuthApiBase, "user">;
  * 1. `user.id(ctx)` → userId or null (exit early)
  * 2. `user.get(ctx, userId)` → user doc (cached per-execution)
  * 3. `user.getActiveGroup(ctx, { userId })` → groupId or null
- * 4. If groupId → `member.resolve(ctx, { userId, groupId })` → role + grants
+ * 4. If groupId → `member.inspect(ctx, { userId, groupId })` → role + grants
  */
-async function resolveAuthContext(auth: any, ctx: any) {
+async function getAuthContext(
+  auth: AuthLike,
+  ctx: any,
+): Promise<AuthContext | null> {
   const userId = await auth.user.id(ctx);
   if (!userId) return null;
   const user = await auth.user.get(ctx, userId);
@@ -425,7 +465,7 @@ async function resolveAuthContext(auth: any, ctx: any) {
   let role: string | null = null;
   let grants: string[] = [];
   if (groupId) {
-    const resolved = await auth.member.resolve(ctx, { userId, groupId });
+    const resolved = await auth.member.inspect(ctx, { userId, groupId });
     if (resolved.membership) {
       role = resolved.roleIds[0] ?? null;
       grants = resolved.grants;
@@ -473,10 +513,10 @@ export function createAuth<
     ) => {
       const enterprise = await connectionApi.get(ctx, enterpriseId);
       if (enterprise === null) {
-        throw new AuthError(
-          "INVALID_PARAMETERS",
-          "Enterprise not found.",
-        ).toConvexError();
+        throw Cv.error({
+          code: "INVALID_PARAMETERS",
+          message: "Enterprise not found.",
+        });
       }
 
       const normalized = domains.map((entry: (typeof domains)[number]) => ({
@@ -486,16 +526,16 @@ export function createAuth<
       const deduped = new Map<string, (typeof normalized)[number]>();
       for (const entry of normalized) {
         if (entry.domain.length === 0) {
-          throw new AuthError(
-            "INVALID_PARAMETERS",
-            "Domain must not be empty.",
-          ).toConvexError();
+          throw Cv.error({
+            code: "INVALID_PARAMETERS",
+            message: "Domain must not be empty.",
+          });
         }
         if (deduped.has(entry.domain)) {
-          throw new AuthError(
-            "INVALID_PARAMETERS",
-            `Duplicate domain: ${entry.domain}`,
-          ).toConvexError();
+          throw Cv.error({
+            code: "INVALID_PARAMETERS",
+            message: `Duplicate domain: ${entry.domain}`,
+          });
         }
         deduped.set(entry.domain, entry);
       }
@@ -505,10 +545,10 @@ export function createAuth<
         (entry) => entry.isPrimary,
       ).length;
       if (primaryCount > 1) {
-        throw new AuthError(
-          "INVALID_PARAMETERS",
-          "Only one primary domain may be set.",
-        ).toConvexError();
+        throw Cv.error({
+          code: "INVALID_PARAMETERS",
+          message: "Only one primary domain may be set.",
+        });
       }
       if (nextDomains.length > 0 && primaryCount === 0) {
         nextDomains[0] = { ...nextDomains[0], isPrimary: true };
@@ -555,7 +595,6 @@ export function createAuth<
 
       const updatedDomains = await domainApi.list(ctx, enterpriseId);
       return {
-        ok: true as const,
         enterpriseId,
         domains: updatedDomains.map(
           (domain: (typeof updatedDomains)[number]) => ({
@@ -629,12 +668,27 @@ export function createAuth<
     },
     http: authResult.auth.http,
 
-    resolve: (ctx: any) => resolveAuthContext(authResult.auth, ctx),
+    context: async (ctx: any) => {
+      const authContext = await getAuthContext(authResult.auth, ctx);
+      if (authContext === null) {
+        throw Cv.error({
+          code: "NOT_SIGNED_IN",
+          message: "Authentication required.",
+        });
+      }
+      return authContext;
+    },
 
     ctx: () => ({
       args: {},
       input: async (ctx: any) => {
-        const authCtx = await resolveAuthContext(authResult.auth, ctx);
+        const authCtx = await getAuthContext(authResult.auth, ctx);
+        if (authCtx === null) {
+          throw Cv.error({
+            code: "NOT_SIGNED_IN",
+            message: "Authentication required.",
+          });
+        }
         return { ctx: { auth: authCtx }, args: {} };
       },
     }),
@@ -645,9 +699,6 @@ export function createAuth<
 // AuthCtx — ctx enrichment for customQuery / customMutation
 // ============================================================================
 
-/** Canonical user document type exposed by Convex Auth. */
-export type UserDoc = Doc<"User">;
-
 /**
  * Configuration for {@link AuthCtx} context enrichment.
  *
@@ -660,17 +711,50 @@ export type AuthCtxConfig<
   /** Allow unauthenticated callers and return `userId: null` / `user: null`. */
   optional?: boolean;
   /**
-   * Attach additional derived fields to the auth context after the user is resolved.
+   * Attach additional derived fields to the auth context after the base auth
+   * context is resolved.
    */
-  resolve?: (ctx: any, user: UserDoc) => Promise<TResolve> | TResolve;
+  resolve?: (
+    ctx: any,
+    user: UserDoc,
+    auth: AuthContext,
+  ) => Promise<TResolve> | TResolve;
+  /**
+   * Override or wrap the base auth resolution used by {@link AuthCtx}.
+   *
+   * Return `undefined` to fall back to the built-in resolver,
+   * `null` for an explicit unauthenticated state, or an
+   * {@link AuthContext} object to provide a pre-resolved auth state.
+   * This is useful for tests, proxy auth, impersonation flows, or any
+   * environment that needs to inject auth without depending on the standard
+   * Convex auth tables.
+   *
+   * @param ctx - The Convex function context.
+   * @param fallback - The built-in auth resolver used by {@link AuthCtx}.
+   * @returns Resolved auth state, `null`, or `undefined` to use the fallback.
+   *
+   * @example
+   * ```ts
+   * const authCtx = AuthCtx(auth, {
+   *   authResolve: async (ctx, fallback) => {
+   *     const injected = getInjectedAuth(ctx);
+   *     return injected ?? (await fallback());
+   *   },
+   * });
+   * ```
+   */
+  authResolve?: (
+    ctx: any,
+    fallback: () => Promise<AuthContext | null>,
+  ) => Promise<AuthContext | null | undefined> | AuthContext | null | undefined;
 };
 
 /**
  * Create a context enrichment for `customQuery` / `customMutation` — optional auth.
  *
  * When `optional: true` is set, unauthenticated requests are allowed.
- * The enriched `ctx.auth` will have `userId: null` and `user: null`
- * for unauthenticated callers.
+ * The enriched `ctx.auth` will have `userId: null`, `user: null`,
+ * `groupId: null`, `role: null`, and `grants: []` for unauthenticated callers.
  *
  * @param auth - The auth API object returned by {@link createAuth}.
  * @param config - Configuration with `optional: true` and an optional
@@ -701,11 +785,7 @@ export function AuthCtx<
     _extra?: any,
   ) => Promise<{
     ctx: {
-      auth: {
-        getUserIdentity: () => Promise<UserIdentity | null>;
-        userId: GenericId<"User"> | null;
-        user: UserDoc | null;
-      } & TResolve;
+      auth: OptionalAuthCtxState & TResolve;
     };
     args: {};
   }>;
@@ -713,10 +793,8 @@ export function AuthCtx<
 /**
  * Create a context enrichment for `customQuery` / `customMutation` — required auth (default).
  *
- * When `optional` is omitted or `false`, the inferred type is the authenticated
- * auth shape. At runtime this helper still resolves instead of throwing, so if
- * no user is signed in the returned `ctx.auth.userId` and `ctx.auth.user` are
- * `null`.
+ * When `optional` is omitted or `false`, unauthenticated requests throw a
+ * structured `ConvexError` before your handler runs.
  *
  * @param auth - The auth API object returned by {@link createAuth}.
  * @param config - Optional configuration with a `resolve` callback
@@ -746,11 +824,7 @@ export function AuthCtx<
     _extra?: any,
   ) => Promise<{
     ctx: {
-      auth: {
-        getUserIdentity: () => Promise<UserIdentity | null>;
-        userId: GenericId<"User">;
-        user: UserDoc;
-      } & TResolve;
+      auth: RequiredAuthCtxState & TResolve;
     };
     args: {};
   }>;
@@ -761,39 +835,31 @@ export function AuthCtx(auth: AuthLike, config?: AuthCtxConfig<any>) {
     args: {},
     input: async (ctx: any, _args: any, _extra?: any) => {
       const nativeAuth = ctx.auth;
-      const modeDispatch =
-        config?.optional === true
-          ? { mode: "optional" as const }
-          : { mode: "required" as const };
-
-      const userContext = await Fx.run(
-        Fx.match(modeDispatch, modeDispatch.mode, {
-          optional: async () => {
-            const userId = await auth.user.id(ctx);
-            if (!userId) {
-              return null;
-            }
-            const user = await auth.user.get(ctx, userId);
-            return { userId, user };
-          },
-          required: async () => {
-            const userId = await auth.user.id(ctx);
-            if (!userId) {
-              return null;
-            }
-            const user = await auth.user.get(ctx, userId);
-            return { userId, user };
-          },
-        }),
-      );
-
-      if (userContext === null) {
+      const getUserIdentity = nativeAuth.getUserIdentity.bind(nativeAuth);
+      const fallback = () => getAuthContext(auth, ctx);
+
+      const authOverride = config?.authResolve
+        ? await config.authResolve(ctx, fallback)
+        : undefined;
+      const resolved =
+        authOverride === undefined ? await fallback() : authOverride;
+
+      if (resolved === null) {
+        if (config?.optional !== true) {
+          throw Cv.error({
+            code: "NOT_SIGNED_IN",
+            message: "Authentication required.",
+          });
+        }
         return {
           ctx: {
             auth: {
-              getUserIdentity: nativeAuth.getUserIdentity.bind(nativeAuth),
+              getUserIdentity,
               userId: null,
               user: null,
+              groupId: null,
+              role: null,
+              grants: [],
             },
           },
           args: {},
@@ -801,15 +867,14 @@ export function AuthCtx(auth: AuthLike, config?: AuthCtxConfig<any>) {
       }
 
       const extra = config?.resolve
-        ? await config.resolve(ctx, userContext.user)
+        ? await config.resolve(ctx, resolved.user, resolved)
         : {};
 
       return {
         ctx: {
           auth: {
-            getUserIdentity: nativeAuth.getUserIdentity.bind(nativeAuth),
-            userId: userContext.userId,
-            user: userContext.user,
+            getUserIdentity,
+            ...resolved,
             ...extra,
           },
         },
@@ -824,9 +889,10 @@ export function AuthCtx(auth: AuthLike, config?: AuthCtxConfig<any>) {
  *
  * Use this to type function parameters or variables that receive the
  * enriched auth context produced by `AuthCtx`. The inferred type includes
- * `userId`, `user`, `getUserIdentity`, and any additional fields added
- * by the `resolve` callback. This is the generic utility for reusing the
- * enriched auth shape without manually duplicating conditional auth types.
+ * `userId`, `user`, `groupId`, `role`, `grants`, `getUserIdentity`, and any
+ * additional fields added by the `resolve` callback. This is the generic
+ * utility for reusing the enriched auth shape without manually duplicating
+ * conditional auth types.
  *
  * @typeParam T - An `AuthCtx` return value (must have an `input` method
  *   that returns `{ ctx: { auth: ... } }`).