@robelest/convex-auth 0.0.4-preview.22 → 0.0.4-preview.24

package/src/server/auth.ts

@@ -4,12 +4,16 @@
  * @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 {
+  createUnauthenticatedAuthContext,
+  getAuthContext as getResolvedAuthContext,
+} from "./context";
 import { Auth as AuthFactory } from "./runtime";
-import { AuthError } from "./authError";
 import type { Doc } from "./types";
 import type {
   AuthAuthorizationConfig,
@@ -41,7 +45,7 @@ type MemberApiWithAuthorization<
   TAuthorization extends AuthAuthorizationConfig | undefined,
 > = Omit<
   ReturnType<typeof AuthFactory>["auth"]["member"],
-  "create" | "list" | "update" | "resolve"
+  "create" | "list" | "update" | "inspect" | "require"
 > & {
   create: (
     ctx: Parameters<
@@ -54,7 +58,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"]
@@ -78,10 +82,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;
@@ -91,10 +106,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}.
  *
@@ -126,30 +140,40 @@ 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 by default.
+   * Pass `{ optional: true }` to get a null-shaped auth object instead.
    *
    * @param ctx - Convex query, mutation, or action context.
-   * @returns The resolved auth context, or `null`.
+   * @param config - Optional auth resolution config. Supports `optional`,
+   *   `resolve`, and `authResolve`.
+   * @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;
-   * ```
-   */
-  resolve: (ctx: any) => Promise<AuthResolvedContext | null>;
+    * ```ts
+    * const authContext = await auth.context(ctx);
+    * const { userId, grants } = authContext;
+    * ```
+    *
+    * @example Optional usage
+    * ```ts
+    * const authContext = await auth.context(ctx, { optional: true });
+    * if (authContext.userId === null) {
+    *   return null;
+    * }
+    * ```
+    */
+  context: AuthContextResolver;
   /**
    * Context enrichment for convex-helpers `customQuery` / `customMutation` /
    * `customAction`.
@@ -158,9 +182,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.
    *
@@ -182,36 +206,30 @@ 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
    *   },
    * });
    * ```
    */
-  ctx: () => {
-    args: Record<string, never>;
-    input: (ctx: any) => Promise<{
-      ctx: { auth: AuthResolvedContext | null };
-      args: Record<string, never>;
-    }>;
-  };
+  ctx: AuthContextFactory;
 };
 
 /**
- * Resolved auth context injected into `ctx.auth` by `auth.ctx()` and
- * {@link AuthCtx}. Also the expected return shape for custom
- * {@link AuthCtxConfig.authResolve | authResolve} hooks.
+ * Current request auth context injected into `ctx.auth` by `auth.ctx()`. 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 { AuthResolvedContext } from "@robelest/convex-auth/server";
+ * import type { AuthContext } from "@robelest/convex-auth/server";
  *
- * const mockAuth: AuthResolvedContext = {
+ * const mockAuth: AuthContext = {
  *   userId: "user123" as Id<"User">,
  *   user: { _id: "user123", email: "test@example.com" },
  *   groupId: "group456",
@@ -220,7 +238,7 @@ export type AuthApiBase<
  * };
  * ```
  */
-export type AuthResolvedContext = {
+export type AuthContext = {
   /** The authenticated user's document ID. */
   userId: GenericId<"User">;
   /** The authenticated user's full document. */
@@ -233,20 +251,84 @@ export type AuthResolvedContext = {
   grants: string[];
 };
 
-type AuthCtxBase = {
-  getUserIdentity: () => Promise<UserIdentity | null>;
-};
-
-type RequiredAuthCtxState = AuthCtxBase & AuthResolvedContext;
-
-type OptionalAuthCtxState = AuthCtxBase & {
+/**
+ * Nullable auth context returned by `auth.context(ctx, { optional: true })`
+ * and injected by `auth.ctx({ optional: true })`.
+ *
+ * Use this when callers may be unauthenticated but you still want a stable
+ * auth-shaped object.
+ *
+ * - `userId` and `user` are `null` when unauthenticated.
+ * - `groupId` and `role` are `null` when no active group is resolved.
+ * - `grants` is `[]` when no membership is resolved.
+ *
+ * @example
+ * ```ts
+ * const authContext = await auth.context(ctx, { optional: true });
+ * if (authContext.userId === null) {
+ *   return null;
+ * }
+ * ```
+ */
+export type OptionalAuthContext = {
+  /** The authenticated user's document ID, or `null` when unauthenticated. */
   userId: GenericId<"User"> | null;
+  /** The authenticated user's full document, or `null` when unauthenticated. */
   user: UserDoc | null;
+  /** The user's active group ID, or `null` if none is set. */
   groupId: string | null;
+  /** The user's primary role in the active group, or `null`. */
   role: string | null;
+  /** Resolved grant strings for the active membership, or `[]`. */
   grants: string[];
 };
 
+type AuthContextBase = {
+  getUserIdentity: () => Promise<UserIdentity | null>;
+};
+
+type RequiredAuthContextState = AuthContextBase & AuthContext;
+
+type OptionalAuthContextState = AuthContextBase & OptionalAuthContext;
+
+type ResolvedAuthContext<TResolve> = AuthContext & TResolve;
+
+type ResolvedOptionalAuthContext<TResolve> = OptionalAuthContext & TResolve;
+
+type AuthContextResolver = {
+  <TResolve extends Record<string, unknown> = Record<string, never>>(
+    ctx: any,
+    config: AuthContextConfig<TResolve> & { optional: true },
+  ): Promise<ResolvedOptionalAuthContext<TResolve>>;
+  <TResolve extends Record<string, unknown> = Record<string, never>>(
+    ctx: any,
+    config?: AuthContextConfig<TResolve>,
+  ): Promise<ResolvedAuthContext<TResolve>>;
+};
+
+type AuthContextCustomization<TAuth> = {
+  args: {};
+  input: (
+    ctx: any,
+    _args: any,
+    _extra?: any,
+  ) => Promise<{
+    ctx: {
+      auth: TAuth;
+    };
+    args: {};
+  }>;
+};
+
+type AuthContextFactory = {
+  <TResolve extends Record<string, unknown> = Record<string, never>>(
+    config: AuthContextConfig<TResolve> & { optional: true },
+  ): AuthContextCustomization<OptionalAuthContextState & TResolve>;
+  <TResolve extends Record<string, unknown> = Record<string, never>>(
+    config?: AuthContextConfig<TResolve>,
+  ): AuthContextCustomization<RequiredAuthContextState & TResolve>;
+};
+
 type InternalSsoApi = ReturnType<typeof AuthFactory>["auth"]["sso"];
 
 type PublicSsoAdminApi = {
@@ -262,7 +344,6 @@ type PublicSsoAdminApi = {
           isPrimary?: boolean;
         }>,
       ) => Promise<{
-        ok: true;
         enterpriseId: string;
         domains: Array<{
           domainId: string;
@@ -277,7 +358,6 @@ type PublicSsoAdminApi = {
           ctx: Parameters<InternalSsoApi["connection"]["create"]>[0],
           args: { enterpriseId: string; domain: string },
         ) => Promise<{
-          ok: true;
           enterpriseId: string;
           domain: string;
           requestedAt: number;
@@ -292,7 +372,6 @@ type PublicSsoAdminApi = {
           ctx: Parameters<InternalSsoApi["connection"]["create"]>[0],
           args: { enterpriseId: string; domain: string },
         ) => Promise<{
-          ok: boolean;
           enterpriseId: string;
           domain: string;
           verifiedAt?: number;
@@ -431,38 +510,54 @@ export type AuthLike = Pick<AuthApiBase, "user" | "member">;
  * });
  * ```
  *
- * @see {@link AuthCtx}
+ * @see {@link AuthContextConfig}
  */
 
 // ---------------------------------------------------------------------------
 // Function builders — shared auth resolution logic
 // ---------------------------------------------------------------------------
 
-/**
- * Resolve auth context for the current user. Returns the enriched
- * `ctx.auth` object or `null` when unauthenticated.
- *
- * Resolution flow:
- * 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
- */
-async function resolveAuthContext(auth: AuthLike, ctx: any) {
-  const userId = await auth.user.id(ctx);
-  if (!userId) return null;
-  const user = await auth.user.get(ctx, userId);
-  const groupId = await auth.user.getActiveGroup(ctx, { userId });
-  let role: string | null = null;
-  let grants: string[] = [];
-  if (groupId) {
-    const resolved = await auth.member.resolve(ctx, { userId, groupId });
-    if (resolved.membership) {
-      role = resolved.roleIds[0] ?? null;
-      grants = resolved.grants;
+async function resolveConfiguredAuthContext(
+  auth: AuthLike,
+  ctx: any,
+  config?: AuthContextConfig<any>,
+): Promise<AuthContext | null> {
+  const fallback = () => getResolvedAuthContext(auth, ctx);
+  const authOverride = config?.authResolve
+    ? await config.authResolve(ctx, fallback)
+    : undefined;
+  return authOverride === undefined ? await fallback() : authOverride;
+}
+
+function createNotSignedInError() {
+  return Cv.error({
+    code: "NOT_SIGNED_IN",
+    message: "Authentication required.",
+  });
+}
+
+async function createPublicAuthContext(
+  auth: AuthLike,
+  ctx: any,
+  config?: AuthContextConfig<any>,
+) {
+  const resolved = await resolveConfiguredAuthContext(auth, ctx, config);
+
+  if (resolved === null) {
+    if (config?.optional !== true) {
+      throw createNotSignedInError();
     }
+    return createUnauthenticatedAuthContext();
   }
-  return { userId, user, groupId, role, grants };
+
+  const extra = config?.resolve
+    ? await config.resolve(ctx, resolved.user, resolved)
+    : {};
+
+  return {
+    ...resolved,
+    ...extra,
+  };
 }
 
 export function createAuth<
@@ -504,10 +599,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]) => ({
@@ -517,16 +612,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);
       }
@@ -536,10 +631,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 };
@@ -586,7 +681,6 @@ export function createAuth<
 
       const updatedDomains = await domainApi.list(ctx, enterpriseId);
       return {
-        ok: true as const,
         enterpriseId,
         domains: updatedDomains.map(
           (domain: (typeof updatedDomains)[number]) => ({
@@ -660,59 +754,72 @@ export function createAuth<
     },
     http: authResult.auth.http,
 
-    resolve: (ctx: any) => resolveAuthContext(authResult.auth, ctx),
+    context: ((ctx: any, config?: AuthContextConfig<any>) =>
+      createPublicAuthContext(authResult.auth, ctx, config)) as AuthContextResolver,
 
-    ctx: () => ({
-      args: {},
-      input: async (ctx: any) => {
-        const authCtx = await resolveAuthContext(authResult.auth, ctx);
-        return { ctx: { auth: authCtx }, args: {} };
-      },
-    }),
+    ctx: ((config?: AuthContextConfig<any>) =>
+      createAuthContextCustomization(authResult.auth, config)) as AuthContextFactory,
   } as unknown as ConvexAuthResult<P, TAuthorization>;
 }
 
 // ============================================================================
-// AuthCtx — ctx enrichment for customQuery / customMutation
+// auth.ctx() — ctx enrichment for customQuery / customMutation
 // ============================================================================
 
 /**
- * Configuration for {@link AuthCtx} context enrichment.
+ * Configuration for {@link createAuth().ctx} context enrichment.
+ *
+ * The same config shape is also used by {@link createAuth().context}.
  *
  * @typeParam TResolve - Extra fields returned from `resolve()` and merged into
  *   the resulting `ctx.auth` object.
+ *
+ * @example
+ * ```ts
+ * const authContext = await auth.context(ctx, {
+ *   resolve: async (_ctx, user, authState) => ({
+ *     email: user.email,
+ *     canWrite: authState.grants.includes("posts.write"),
+ *   }),
+ * });
+ * ```
  */
-export type AuthCtxConfig<
+export type AuthContextConfig<
   TResolve extends Record<string, unknown> = Record<string, never>,
 > = {
-  /** Allow unauthenticated callers and return `userId: null` / `user: null`. */
+  /**
+   * Allow unauthenticated callers and return a null-shaped auth object instead
+   * of throwing `NOT_SIGNED_IN`.
+   */
   optional?: boolean;
   /**
    * Attach additional derived fields to the auth context after the base auth
    * context is resolved.
+   *
+   * This callback runs only when a user is authenticated.
    */
   resolve?: (
     ctx: any,
     user: UserDoc,
-    auth: AuthResolvedContext,
+    auth: AuthContext,
   ) => Promise<TResolve> | TResolve;
   /**
-   * Override or wrap the base auth resolution used by {@link AuthCtx}.
+   * Override or wrap the base auth resolution used by {@link createAuth().ctx}.
    *
    * Return `undefined` to fall back to the built-in resolver,
    * `null` for an explicit unauthenticated state, or an
-   * {@link AuthResolvedContext} object to provide a pre-resolved auth state.
+   * {@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}.
+   * @param fallback - The built-in auth resolver used by {@link createAuth().ctx}.
    * @returns Resolved auth state, `null`, or `undefined` to use the fallback.
    *
    * @example
    * ```ts
-   * const authCtx = AuthCtx(auth, {
+   * const authCtx = auth.ctx({
    *   authResolve: async (ctx, fallback) => {
    *     const injected = getInjectedAuth(ctx);
    *     return injected ?? (await fallback());
@@ -722,12 +829,8 @@ export type AuthCtxConfig<
    */
   authResolve?: (
     ctx: any,
-    fallback: () => Promise<AuthResolvedContext | null>,
-  ) =>
-    | Promise<AuthResolvedContext | null | undefined>
-    | AuthResolvedContext
-    | null
-    | undefined;
+    fallback: () => Promise<AuthContext | null>,
+  ) => Promise<AuthContext | null | undefined> | AuthContext | null | undefined;
 };
 
 /**
@@ -737,7 +840,6 @@ export type AuthCtxConfig<
  * 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
  *   `resolve` callback for attaching extra fields to the auth context.
  * @returns An object with `args` and `input` compatible with Convex
@@ -745,42 +847,21 @@ export type AuthCtxConfig<
  *
  * @example
  * ```ts
- * const authCtx = AuthCtx(auth, {
- *   optional: true,
- *   resolve: async (_ctx, user) => ({ plan: user?.extend?.plan ?? null }),
- * });
- * ```
+    * const authCtx = auth.ctx({
+    *   optional: true,
+    *   resolve: async (_ctx, user) => ({ plan: user.extend?.plan ?? null }),
+    * });
+    * ```
  *
  * @see {@link createAuth}
  */
-export function AuthCtx<
-  TResolve extends Record<string, unknown> = Record<string, never>,
->(
-  auth: AuthLike,
-  config: AuthCtxConfig<TResolve> & { optional: true },
-): {
-  args: {};
-  input: (
-    ctx: any,
-    _args: any,
-    _extra?: any,
-  ) => Promise<{
-    ctx: {
-      auth: OptionalAuthCtxState & TResolve;
-    };
-    args: {};
-  }>;
-};
+
 /**
  * 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` / `ctx.auth.user` are
- * `null`, `ctx.auth.groupId` / `ctx.auth.role` are `null`, and
- * `ctx.auth.grants` is `[]`.
+ * 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
  *   for attaching extra fields to the auth context.
  * @returns An object with `args` and `input` compatible with Convex
@@ -788,56 +869,33 @@ export function AuthCtx<
  *
  * @example
  * ```ts
- * const authCtx = AuthCtx(auth, {
- *   resolve: async (_ctx, user) => ({ email: user.email }),
- * });
- * ```
+    * const authCtx = auth.ctx({
+    *   resolve: async (_ctx, user) => ({ email: user.email }),
+    * });
+    * ```
  *
  * @see {@link createAuth}
  */
-export function AuthCtx<
-  TResolve extends Record<string, unknown> = Record<string, never>,
->(
+function createAuthContextCustomization(
   auth: AuthLike,
-  config?: AuthCtxConfig<TResolve>,
-): {
-  args: {};
-  input: (
-    ctx: any,
-    _args: any,
-    _extra?: any,
-  ) => Promise<{
-    ctx: {
-      auth: RequiredAuthCtxState & TResolve;
-    };
-    args: {};
-  }>;
-};
-// Implementation
-export function AuthCtx(auth: AuthLike, config?: AuthCtxConfig<any>) {
+  config?: AuthContextConfig<any>,
+) {
   return {
     args: {},
     input: async (ctx: any, _args: any, _extra?: any) => {
       const nativeAuth = ctx.auth;
       const getUserIdentity = nativeAuth.getUserIdentity.bind(nativeAuth);
-      const fallback = () => resolveAuthContext(auth, ctx);
-
-      const authOverride = config?.authResolve
-        ? await config.authResolve(ctx, fallback)
-        : undefined;
-      const resolved =
-        authOverride === undefined ? await fallback() : authOverride;
+      const resolved = await resolveConfiguredAuthContext(auth, ctx, config);
 
       if (resolved === null) {
+        if (config?.optional !== true) {
+          throw createNotSignedInError();
+        }
         return {
           ctx: {
             auth: {
               getUserIdentity,
-              userId: null,
-              user: null,
-              groupId: null,
-              role: null,
-              grants: [],
+              ...createUnauthenticatedAuthContext(),
             },
           },
           args: {},
@@ -863,21 +921,21 @@ export function AuthCtx(auth: AuthLike, config?: AuthCtxConfig<any>) {
 }
 
 /**
- * Extract the resolved `auth` context type from an {@link AuthCtx} instance.
+ * Extract the resolved `auth` context type from an `auth.ctx()` customization.
  *
  * Use this to type function parameters or variables that receive the
- * enriched auth context produced by `AuthCtx`. The inferred type includes
+ * enriched auth context produced by `auth.ctx()`. The inferred type includes
  * `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
+ * @typeParam T - An `auth.ctx()` return value (must have an `input` method
  *   that returns `{ ctx: { auth: ... } }`).
  *
  * @example
  * ```ts
- * const authCtx = AuthCtx(auth, {
+ * const authCtx = auth.ctx({
  *   resolve: async (ctx, user) => ({ orgId: user.orgId }),
  * });
  * type Auth = InferAuth<typeof authCtx>;