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

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

@@ -12,7 +12,7 @@ import { GenericId } from "convex/values";
 type AuthConfig = Omit<ConvexAuthConfig, "component">;
 /** Canonical user document type exposed by Convex Auth. */
 type UserDoc = Doc<"User">;
-type MemberApiWithAuthorization<TAuthorization extends AuthAuthorizationConfig | undefined> = Omit<ReturnType<typeof Auth>["auth"]["member"], "create" | "list" | "update" | "resolve"> & {
+type MemberApiWithAuthorization<TAuthorization extends AuthAuthorizationConfig | undefined> = Omit<ReturnType<typeof Auth>["auth"]["member"], "create" | "list" | "update" | "inspect" | "require"> & {
   create: (ctx: Parameters<ReturnType<typeof Auth>["auth"]["member"]["create"]>[0], data: {
     groupId: string;
     userId: string;
@@ -20,7 +20,6 @@ type MemberApiWithAuthorization<TAuthorization extends AuthAuthorizationConfig |
     status?: string;
     extend?: Record<string, unknown>;
   }) => Promise<{
-    ok: true;
     memberId: string;
   }>;
   list: (ctx: Parameters<ReturnType<typeof Auth>["auth"]["member"]["list"]>[0], opts?: {
@@ -38,17 +37,22 @@ type MemberApiWithAuthorization<TAuthorization extends AuthAuthorizationConfig |
   update: (ctx: Parameters<ReturnType<typeof Auth>["auth"]["member"]["update"]>[0], memberId: string, data: Record<string, unknown> & {
     roleIds?: AuthRoleId<TAuthorization>[];
   }) => Promise<{
-    ok: true;
     memberId: string;
   }>;
-  resolve: (ctx: Parameters<ReturnType<typeof Auth>["auth"]["member"]["resolve"]>[0], opts: {
+  inspect: (ctx: Parameters<ReturnType<typeof Auth>["auth"]["member"]["inspect"]>[0], opts: {
+    userId: string;
+    groupId: string;
+    ancestry?: boolean;
+    maxDepth?: number;
+  }) => ReturnType<ReturnType<typeof Auth>["auth"]["member"]["inspect"]>;
+  require: (ctx: Parameters<ReturnType<typeof Auth>["auth"]["member"]["require"]>[0], opts: {
     userId: string;
     groupId: string;
     ancestry?: boolean;
     roleIds?: AuthRoleId<TAuthorization>[];
     grants?: AuthGrant<TAuthorization>[];
     maxDepth?: number;
-  }) => ReturnType<ReturnType<typeof Auth>["auth"]["member"]["resolve"]>;
+  }) => ReturnType<ReturnType<typeof Auth>["auth"]["member"]["require"]>;
 };
 /**
  * The base auth API surface returned by {@link createAuth}.
@@ -79,30 +83,40 @@ type AuthApiBase<TAuthorization extends AuthAuthorizationConfig | undefined = un
   key: ReturnType<typeof Auth>["auth"]["key"];
   http: ReturnType<typeof Auth>["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`.
@@ -111,9 +125,9 @@ type AuthApiBase<TAuthorization extends AuthAuthorizationConfig | undefined = un
    * 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.
    *
@@ -135,37 +149,29 @@ type AuthApiBase<TAuthorization extends AuthAuthorizationConfig | undefined = un
    * 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",
@@ -174,23 +180,66 @@ type AuthApiBase<TAuthorization extends AuthAuthorizationConfig | undefined = un
  * };
  * ```
  */
-type AuthResolvedContext = {
+type AuthContext = {
   /** The authenticated user's document ID. */userId: GenericId<"User">; /** The authenticated user's full document. */
   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`. */
   role: string | null; /** Resolved grant strings from the user's role definitions. */
   grants: string[];
 };
-type 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;
+ * }
+ * ```
+ */
+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 RequiredAuthCtxState = AuthCtxBase & AuthResolvedContext;
-type OptionalAuthCtxState = AuthCtxBase & {
-  userId: GenericId<"User"> | null;
-  user: UserDoc | null;
-  groupId: string | null;
-  role: string | null;
-  grants: string[];
+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 Auth>["auth"]["sso"];
 type PublicSsoAdminApi = {
@@ -202,7 +251,6 @@ type PublicSsoAdminApi = {
         domain: string;
         isPrimary?: boolean;
       }>) => Promise<{
-        ok: true;
         enterpriseId: string;
         domains: Array<{
           domainId: string;
@@ -217,7 +265,6 @@ type PublicSsoAdminApi = {
           enterpriseId: string;
           domain: string;
         }) => Promise<{
-          ok: true;
           enterpriseId: string;
           domain: string;
           requestedAt: number;
@@ -232,7 +279,6 @@ type PublicSsoAdminApi = {
           enterpriseId: string;
           domain: string;
         }) => Promise<{
-          ok: boolean;
           enterpriseId: string;
           domain: string;
           verifiedAt?: number;
@@ -309,35 +355,53 @@ declare function createAuth<P extends AuthProviderConfig[], TAuthorization exten
   authorization?: TAuthorization;
 }): ConvexAuthResult<P, TAuthorization>;
 /**
- * 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"),
+ *   }),
+ * });
+ * ```
  */
-type AuthCtxConfig<TResolve extends Record<string, unknown> = Record<string, never>> = {
-  /** Allow unauthenticated callers and return `userId: null` / `user: null`. */optional?: boolean;
+type AuthContextConfig<TResolve extends Record<string, unknown> = Record<string, never>> = {
+  /**
+   * 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) => Promise<TResolve> | TResolve;
+  resolve?: (ctx: any, user: UserDoc, 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());
@@ -345,91 +409,24 @@ type AuthCtxConfig<TResolve extends Record<string, unknown> = Record<string, nev
    * });
    * ```
    */
-  authResolve?: (ctx: any, fallback: () => Promise<AuthResolvedContext | null>) => Promise<AuthResolvedContext | null | undefined> | AuthResolvedContext | 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`, `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
- *   custom function builders.
- *
- * @example
- * ```ts
- * const authCtx = AuthCtx(auth, {
- *   optional: true,
- *   resolve: async (_ctx, user) => ({ plan: user?.extend?.plan ?? null }),
- * });
- * ```
- *
- * @see {@link createAuth}
- */
-declare 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 `[]`.
- *
- * @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
- *   custom function builders.
- *
- * @example
- * ```ts
- * const authCtx = AuthCtx(auth, {
- *   resolve: async (_ctx, user) => ({ email: user.email }),
- * });
- * ```
- *
- * @see {@link createAuth}
- */
-declare function AuthCtx<TResolve extends Record<string, unknown> = Record<string, never>>(auth: AuthLike, config?: AuthCtxConfig<TResolve>): {
-  args: {};
-  input: (ctx: any, _args: any, _extra?: any) => Promise<{
-    ctx: {
-      auth: RequiredAuthCtxState & TResolve;
-    };
-    args: {};
-  }>;
+  authResolve?: (ctx: any, fallback: () => Promise<AuthContext | null>) => Promise<AuthContext | null | undefined> | AuthContext | null | undefined;
 };
 /**
- * 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>;
@@ -446,5 +443,5 @@ type InferAuth<T extends {
   }>;
 }> = Awaited<ReturnType<T["input"]>>["ctx"]["auth"];
 //#endregion
-export { AuthApi, AuthConfig, AuthCtx, AuthCtxConfig, AuthResolvedContext, InferAuth, UserDoc, createAuth };
+export { AuthApi, AuthConfig, AuthContext, AuthContextConfig, InferAuth, OptionalAuthContext, UserDoc, createAuth };
 //# sourceMappingURL=auth.d.ts.map

package/dist/component/server/auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","names":[],"sources":["../../../src/server/auth.ts"],"mappings":"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"}
+{"version":3,"file":"auth.d.ts","names":[],"sources":["../../../src/server/auth.ts"],"mappings":"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"}

package/dist/component/server/auth.js

@@ -1,8 +1,14 @@
-import { AuthError } from "./authError.js";
+import { createUnauthenticatedAuthContext, getAuthContext } from "./context.js";
 import { Auth } from "./runtime.js";
+import { Cv } from "@robelest/fx/convex";
 
 //#region src/server/auth.ts
 /**
+* Auth configuration helpers for Convex Auth.
+*
+* @module
+*/
+/**
 * Create an auth API object.
 *
 * When `new SSO()` is included in providers, `auth.sso` and `auth.scim`
@@ -26,41 +32,29 @@ import { Auth } from "./runtime.js";
 * });
 * ```
 *
-* @see {@link AuthCtx}
-*/
-/**
-* 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
+* @see {@link AuthContextConfig}
 */
-async function resolveAuthContext(auth, ctx) {
-	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 = null;
-	let grants = [];
-	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, ctx, config) {
+	const fallback = () => getAuthContext(auth, ctx);
+	const authOverride = config?.authResolve ? await config.authResolve(ctx, fallback) : void 0;
+	return authOverride === void 0 ? await fallback() : authOverride;
+}
+function createNotSignedInError() {
+	return Cv.error({
+		code: "NOT_SIGNED_IN",
+		message: "Authentication required."
+	});
+}
+async function createPublicAuthContext(auth, ctx, config) {
+	const resolved = await resolveConfiguredAuthContext(auth, ctx, config);
+	if (resolved === null) {
+		if (config?.optional !== true) throw createNotSignedInError();
+		return createUnauthenticatedAuthContext();
 	}
+	const extra = config?.resolve ? await config.resolve(ctx, resolved.user, resolved) : {};
 	return {
-		userId,
-		user,
-		groupId,
-		role,
-		grants
+		...resolved,
+		...extra
 	};
 }
 function createAuth(component, config) {
@@ -72,20 +66,32 @@ function createAuth(component, config) {
 	const { domain: domainApi, scim: scimApi, connection: connectionApi, audit: auditApi, webhook: webhookApi, oidc: oidcApi, saml: samlApi, ...restSso } = authResult.auth.sso;
 	const setEnterpriseDomains = async (ctx, enterpriseId, domains) => {
 		const enterprise = await connectionApi.get(ctx, enterpriseId);
-		if (enterprise === null) throw new AuthError("INVALID_PARAMETERS", "Enterprise not found.").toConvexError();
+		if (enterprise === null) throw Cv.error({
+			code: "INVALID_PARAMETERS",
+			message: "Enterprise not found."
+		});
 		const normalized = domains.map((entry) => ({
 			...entry,
 			domain: entry.domain.trim().toLowerCase()
 		}));
 		const deduped = /* @__PURE__ */ new Map();
 		for (const entry of normalized) {
-			if (entry.domain.length === 0) throw new AuthError("INVALID_PARAMETERS", "Domain must not be empty.").toConvexError();
-			if (deduped.has(entry.domain)) throw new AuthError("INVALID_PARAMETERS", `Duplicate domain: ${entry.domain}`).toConvexError();
+			if (entry.domain.length === 0) throw Cv.error({
+				code: "INVALID_PARAMETERS",
+				message: "Domain must not be empty."
+			});
+			if (deduped.has(entry.domain)) throw Cv.error({
+				code: "INVALID_PARAMETERS",
+				message: `Duplicate domain: ${entry.domain}`
+			});
 			deduped.set(entry.domain, entry);
 		}
 		const nextDomains = [...deduped.values()];
 		const primaryCount = nextDomains.filter((entry) => entry.isPrimary).length;
-		if (primaryCount > 1) throw new AuthError("INVALID_PARAMETERS", "Only one primary domain may be set.").toConvexError();
+		if (primaryCount > 1) 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
@@ -109,7 +115,6 @@ function createAuth(component, config) {
 			});
 		}
 		return {
-			ok: true,
 			enterpriseId,
 			domains: (await domainApi.list(ctx, enterpriseId)).map((domain) => ({
 				domainId: domain._id,
@@ -168,38 +173,69 @@ function createAuth(component, config) {
 			validate: scimApi.validate
 		} },
 		http: authResult.auth.http,
-		resolve: (ctx) => resolveAuthContext(authResult.auth, ctx),
-		ctx: () => ({
-			args: {},
-			input: async (ctx) => {
-				return {
-					ctx: { auth: await resolveAuthContext(authResult.auth, ctx) },
-					args: {}
-				};
-			}
-		})
+		context: ((ctx, config$1) => createPublicAuthContext(authResult.auth, ctx, config$1)),
+		ctx: ((config$1) => createAuthContextCustomization(authResult.auth, config$1))
 	};
 }
-function AuthCtx(auth, config) {
+/**
+* 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`, `user: null`,
+* `groupId: null`, `role: null`, and `grants: []` for unauthenticated callers.
+*
+* @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
+*   custom function builders.
+*
+* @example
+* ```ts
+* const authCtx = auth.ctx({
+*   optional: true,
+*   resolve: async (_ctx, user) => ({ plan: user.extend?.plan ?? null }),
+* });
+* ```
+*
+* @see {@link createAuth}
+*/
+/**
+* Create a context enrichment for `customQuery` / `customMutation` — required auth (default).
+*
+* When `optional` is omitted or `false`, unauthenticated requests throw a
+* structured `ConvexError` before your handler runs.
+*
+* @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
+*   custom function builders.
+*
+* @example
+* ```ts
+* const authCtx = auth.ctx({
+*   resolve: async (_ctx, user) => ({ email: user.email }),
+* });
+* ```
+*
+* @see {@link createAuth}
+*/
+function createAuthContextCustomization(auth, config) {
 	return {
 		args: {},
 		input: async (ctx, _args, _extra) => {
 			const nativeAuth = ctx.auth;
 			const getUserIdentity = nativeAuth.getUserIdentity.bind(nativeAuth);
-			const fallback = () => resolveAuthContext(auth, ctx);
-			const authOverride = config?.authResolve ? await config.authResolve(ctx, fallback) : void 0;
-			const resolved = authOverride === void 0 ? await fallback() : authOverride;
-			if (resolved === null) return {
-				ctx: { auth: {
-					getUserIdentity,
-					userId: null,
-					user: null,
-					groupId: null,
-					role: null,
-					grants: []
-				} },
-				args: {}
-			};
+			const resolved = await resolveConfiguredAuthContext(auth, ctx, config);
+			if (resolved === null) {
+				if (config?.optional !== true) throw createNotSignedInError();
+				return {
+					ctx: { auth: {
+						getUserIdentity,
+						...createUnauthenticatedAuthContext()
+					} },
+					args: {}
+				};
+			}
 			const extra = config?.resolve ? await config.resolve(ctx, resolved.user, resolved) : {};
 			return {
 				ctx: { auth: {
@@ -214,5 +250,5 @@ function AuthCtx(auth, config) {
 }
 
 //#endregion
-export { AuthCtx, createAuth };
+export { createAuth };
 //# sourceMappingURL=auth.js.map