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

package/README.md

@@ -20,7 +20,7 @@ one setup API, full TypeScript support.
 - **Groups, memberships, invites** — hierarchical multi-tenancy with roles.
 - **SSR support** — framework-agnostic httpOnly cookie API (SvelteKit, TanStack
   Start, Next.js).
-- **Context enrichment** — zero-boilerplate `ctx.auth.userId` via `AuthCtx`.
+- **Context enrichment** — zero-boilerplate `ctx.auth.userId` via `auth.ctx()`.
 
 ## Install
 
@@ -105,11 +105,11 @@ import { auth } from "./auth";
 
 const convex = createBuilder<DataModel>();
 
+// `auth.context(ctx)` resolves { userId, user, groupId, role, grants }
+// and throws before the handler runs when unauthenticated.
 const withRequiredAuth = convex.createMiddleware<any, { auth: any }>(
   async (ctx, next) => {
-    const userId = await auth.user.require(ctx);
-    const user = await auth.user.get(ctx, userId);
-    return next({ ...ctx, auth: { ...ctx.auth, userId, user } });
+    return next({ ...ctx, auth: await auth.context(ctx) });
   },
 );
 
@@ -117,19 +117,18 @@ export const query = convex.query().use(withRequiredAuth).extend(WithZod);
 export const mutation = convex.mutation().use(withRequiredAuth).extend(WithZod);
 ```
 
-`AuthCtx` from `@robelest/convex-auth/component` remains supported if your
-project already uses `convex-helpers`.
+`auth.ctx()` works with `convex-helpers` and other custom builder setups.
 
 ## Providers
 
 | Provider          | Import                                                                  |
 | ----------------- | ----------------------------------------------------------------------- |
 | OAuth (Arctic)    | `import { OAuth } from "@robelest/convex-auth/providers"`               |
-| Password          | `import { Password } from "@robelest/convex-auth/providers/password"`   |
-| Passkey           | `import { Passkey } from "@robelest/convex-auth/providers/passkey"`     |
-| TOTP              | `import { Totp } from "@robelest/convex-auth/providers/totp"`           |
-| Phone/SMS         | `import { phone } from "@robelest/convex-auth/providers/phone"`         |
-| Anonymous         | `import { Anonymous } from "@robelest/convex-auth/providers/anonymous"` |
+| Password          | `import { Password } from "@robelest/convex-auth/providers"`            |
+| Passkey           | `import { Passkey } from "@robelest/convex-auth/providers"`             |
+| TOTP              | `import { Totp } from "@robelest/convex-auth/providers"`                |
+| Phone/SMS         | `import { Phone } from "@robelest/convex-auth/providers"`               |
+| Anonymous         | `import { Anonymous } from "@robelest/convex-auth/providers"`           |
 | Device (RFC 8628) | `import { Device } from "@robelest/convex-auth/providers"`              |
 
 ## Enterprise

package/dist/component/index.js

@@ -1,3 +1,3 @@
-import { AuthCtx, createAuth } from "./server/auth.js";
+import { createAuth } from "./server/auth.js";
 
-export { AuthCtx, createAuth };
+export { createAuth };

package/dist/component/model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"model.d.ts","names":[],"sources":["../../src/component/model.ts"],"mappings":";;;cAqMa,gBAAA,mBAAgB,OAAA;cAI3B,gBAAA,CAAA,SAAA;;;;;;;;;;cAqBW,WAAA,mBAAW,OAAA;;;;UAatB,gBAAA,CAAA,SAAA;;;;;;;;;;;;;;;;;;;;;;;;;cAEW,cAAA,mBAAc,OAAA;;;UAUzB,gBAAA,CAAA,SAAA;;;;;;;;;;;;;;;;;;;;cA8CW,UAAA,mBAAU,OAAA;;;;;;;;;;;;;UAcrB,gBAAA,CAAA,SAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAEW,cAAA,mBAAc,OAAA;WAUzB,gBAAA,CAAA,SAAA"}
+{"version":3,"file":"model.d.ts","names":[],"sources":["../../src/component/model.ts"],"mappings":"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"}

package/dist/component/schema.d.ts

@@ -15,10 +15,10 @@ declare const _default: convex_server66.SchemaDefinition<{
    * and multiple concurrent sessions.
    */
   User: convex_server66.TableDefinition<convex_values121.VObject<{
-    phone?: string | undefined;
+    email?: string | undefined;
     extend?: any;
     name?: string | undefined;
-    email?: string | undefined;
+    phone?: string | undefined;
     image?: string | undefined;
     emailVerificationTime?: number | undefined;
     phoneVerificationTime?: number | undefined;
@@ -32,7 +32,7 @@ declare const _default: convex_server66.SchemaDefinition<{
     phoneVerificationTime: convex_values121.VFloat64<number | undefined, "optional">;
     isAnonymous: convex_values121.VBoolean<boolean | undefined, "optional">;
     extend: convex_values121.VAny<any, "optional", string>;
-  }, "required", "phone" | "extend" | "name" | "email" | "image" | "emailVerificationTime" | "phoneVerificationTime" | "isAnonymous" | `extend.${string}`>, {
+  }, "required", "email" | "extend" | "name" | "phone" | "image" | "emailVerificationTime" | "phoneVerificationTime" | "isAnonymous" | `extend.${string}`>, {
     email: ["email", "_creationTime"];
     email_verified: ["email", "emailVerificationTime", "_creationTime"];
     phone: ["phone", "_creationTime"];
@@ -336,9 +336,9 @@ declare const _default: convex_server66.SchemaDefinition<{
    * invite links where neither is known upfront.
    */
   GroupInvite: convex_server66.TableDefinition<convex_values121.VObject<{
+    email?: string | undefined;
     groupId?: convex_values121.GenericId<"Group"> | undefined;
     extend?: any;
-    email?: string | undefined;
     role?: string | undefined;
     roleIds?: string[] | undefined;
     invitedByUserId?: convex_values121.GenericId<"User"> | undefined;
@@ -359,7 +359,7 @@ declare const _default: convex_server66.SchemaDefinition<{
     acceptedByUserId: convex_values121.VId<convex_values121.GenericId<"User"> | undefined, "optional">;
     acceptedTime: convex_values121.VFloat64<number | undefined, "optional">;
     extend: convex_values121.VAny<any, "optional", string>;
-  }, "required", "groupId" | "extend" | "status" | "email" | `extend.${string}` | "role" | "roleIds" | "invitedByUserId" | "tokenHash" | "expiresTime" | "acceptedByUserId" | "acceptedTime">, {
+  }, "required", "email" | "groupId" | "extend" | "status" | `extend.${string}` | "role" | "roleIds" | "invitedByUserId" | "tokenHash" | "expiresTime" | "acceptedByUserId" | "acceptedTime">, {
     token_hash: ["tokenHash", "_creationTime"];
     status: ["status", "_creationTime"];
     email_status: ["email", "status", "_creationTime"];

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

@@ -87,9 +87,12 @@ type AuthApiBase<TAuthorization extends AuthAuthorizationConfig | undefined = un
    * this in fluent-convex middleware, custom wrappers, or anywhere you
    * need the current `{ userId, user, groupId, role, grants }` object.
    *
-   * Throws a structured `ConvexError` when unauthenticated.
+   * 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.
+   * @param config - Optional auth resolution config. Supports `optional`,
+   *   `resolve`, and `authResolve`.
    * @returns The current auth context.
    *
    * @example fluent-convex middleware
@@ -100,12 +103,20 @@ type AuthApiBase<TAuthorization extends AuthAuthorizationConfig | undefined = un
    * ```
    *
    * @example Direct usage in a handler
-   * ```ts
-   * const authContext = await auth.context(ctx);
-   * const { userId, grants } = authContext;
-   * ```
-   */
-  context: (ctx: any) => Promise<AuthContext>;
+    * ```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`.
@@ -144,21 +155,13 @@ type AuthApiBase<TAuthorization extends AuthAuthorizationConfig | undefined = un
    * });
    * ```
    */
-  ctx: () => {
-    args: Record<string, never>;
-    input: (ctx: any) => Promise<{
-      ctx: {
-        auth: AuthContext;
-      };
-      args: Record<string, never>;
-    }>;
-  };
+  ctx: AuthContextFactory;
 };
 /**
- * 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.
+ * 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.
  *
  * - `groupId` is `null` when the user has no active group set.
  * - `role` is `null` when no active group or no membership is resolved.
@@ -184,16 +187,59 @@ type AuthContext = {
   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 & AuthContext;
-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 = {
@@ -309,20 +355,38 @@ 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: 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
@@ -332,12 +396,12 @@ type AuthCtxConfig<TResolve extends Record<string, unknown> = Record<string, nev
    * 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());
@@ -348,85 +412,21 @@ type AuthCtxConfig<TResolve extends Record<string, unknown> = Record<string, nev
   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`, `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`, 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
- *   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: {};
-  }>;
-};
-/**
- * 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>;
@@ -443,5 +443,5 @@ type InferAuth<T extends {
   }>;
 }> = Awaited<ReturnType<T["input"]>>["ctx"]["auth"];
 //#endregion
-export { AuthApi, AuthConfig, AuthContext, AuthCtx, AuthCtxConfig, 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,3 +1,4 @@
+import { createUnauthenticatedAuthContext, getAuthContext } from "./context.js";
 import { Auth } from "./runtime.js";
 import { Cv } from "@robelest/fx/convex";
 
@@ -31,41 +32,29 @@ import { Cv } from "@robelest/fx/convex";
 * });
 * ```
 *
-* @see {@link AuthCtx}
+* @see {@link AuthContextConfig}
 */
-/**
-* 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.inspect(ctx, { userId, groupId })` → role + grants
-*/
-async function getAuthContext(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.inspect(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) {
@@ -184,52 +173,65 @@ function createAuth(component, config) {
 			validate: scimApi.validate
 		} },
 		http: authResult.auth.http,
-		context: async (ctx) => {
-			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) => {
-				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: {}
-				};
-			}
-		})
+		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 = () => getAuthContext(auth, ctx);
-			const authOverride = config?.authResolve ? await config.authResolve(ctx, fallback) : void 0;
-			const resolved = authOverride === void 0 ? await fallback() : authOverride;
+			const resolved = await resolveConfiguredAuthContext(auth, ctx, config);
 			if (resolved === null) {
-				if (config?.optional !== true) throw Cv.error({
-					code: "NOT_SIGNED_IN",
-					message: "Authentication required."
-				});
+				if (config?.optional !== true) throw createNotSignedInError();
 				return {
 					ctx: { auth: {
 						getUserIdentity,
-						userId: null,
-						user: null,
-						groupId: null,
-						role: null,
-						grants: []
+						...createUnauthenticatedAuthContext()
 					} },
 					args: {}
 				};
@@ -248,5 +250,5 @@ function AuthCtx(auth, config) {
 }
 
 //#endregion
-export { AuthCtx, createAuth };
+export { createAuth };
 //# sourceMappingURL=auth.js.map