@robelest/convex-auth 0.0.4-preview.18 → 0.0.4-preview.19

package/dist/runtime/proxy.js

@@ -0,0 +1,70 @@
+import { Fx } from "@robelest/fx";
+import { ConvexError } from "convex/values";
+
+//#region src/client/runtime/proxy.ts
+const NETWORK_ERROR_PATTERN = /(network|fetch|load failed|failed to fetch)/i;
+/** @internal */
+function isTransientNetworkError(error) {
+	return error instanceof TypeError || error instanceof Error && NETWORK_ERROR_PATTERN.test(error.message || "");
+}
+/** @internal */
+function isRetriableProxyRefreshError(error) {
+	if (isTransientNetworkError(error)) return true;
+	if (!(error instanceof Error)) return false;
+	const statusMatch = error.message.match(/Proxy request failed:\s*(\d{3})/);
+	if (statusMatch === null) return false;
+	const statusCode = Number(statusMatch[1]);
+	return statusCode >= 500 && statusCode < 600;
+}
+/** @internal */
+function createProxyHelpers(args) {
+	const { proxy } = args;
+	const resolveProxyUrl = () => {
+		const origin = typeof window !== "undefined" && typeof window.location?.origin === "string" ? window.location.origin : typeof location !== "undefined" && typeof location.origin === "string" ? location.origin : null;
+		if (origin !== null) return new URL(proxy, origin).toString();
+		return Fx.run(Fx.from({
+			ok: () => new URL(proxy).toString(),
+			err: () => proxy
+		}).pipe(Fx.recover((fallback) => Fx.succeed(fallback))));
+	};
+	const isAbsoluteUrl = (value) => {
+		return Fx.run(Fx.from({
+			ok: () => {
+				new URL(value);
+				return true;
+			},
+			err: () => false
+		}).pipe(Fx.recover((v) => Fx.succeed(v))));
+	};
+	const proxyFetch = async (body) => {
+		const proxyUrl = await resolveProxyUrl();
+		if (typeof window === "undefined" && !await isAbsoluteUrl(proxyUrl)) throw new Error(`Cannot call relative proxy URL \`${proxy}\` without a browser origin. Pass an absolute proxy URL for server runtimes.`);
+		const response = await fetch(proxyUrl, {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			credentials: "include",
+			body: JSON.stringify(body)
+		});
+		if (!response.ok) {
+			const errorBody = await Fx.run(Fx.from({
+				ok: () => response.json(),
+				err: () => ({})
+			}).pipe(Fx.recover((fallback) => Fx.succeed(fallback))));
+			if (typeof errorBody === "object" && errorBody !== null && "authError" in errorBody && typeof errorBody.authError === "object") throw new ConvexError(errorBody.authError);
+			throw new Error(errorBody.error ?? `Proxy request failed: ${response.status}`);
+		}
+		return Fx.run(Fx.from({
+			ok: () => response.json(),
+			err: () => /* @__PURE__ */ new Error("Proxy response was not valid JSON")
+		}).pipe(Fx.recover((e) => Fx.fatal(e))));
+	};
+	return {
+		isAbsoluteUrl,
+		proxyFetch,
+		resolveProxyUrl
+	};
+}
+
+//#endregion
+export { createProxyHelpers, isRetriableProxyRefreshError, isTransientNetworkError };
+//# sourceMappingURL=proxy.js.map

package/dist/runtime/proxy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy.js","names":[],"sources":["../../src/client/runtime/proxy.ts"],"sourcesContent":["import { Fx } from \"@robelest/fx\";\nimport { ConvexError, type Value } from \"convex/values\";\n\nconst NETWORK_ERROR_PATTERN = /(network|fetch|load failed|failed to fetch)/i;\n\n/** @internal */\nexport function isTransientNetworkError(error: unknown): boolean {\n  return (\n    error instanceof TypeError ||\n    (error instanceof Error && NETWORK_ERROR_PATTERN.test(error.message || \"\"))\n  );\n}\n\n/** @internal */\nexport function isRetriableProxyRefreshError(error: unknown): boolean {\n  if (isTransientNetworkError(error)) {\n    return true;\n  }\n  if (!(error instanceof Error)) {\n    return false;\n  }\n  const statusMatch = error.message.match(/Proxy request failed:\\s*(\\d{3})/);\n  if (statusMatch === null) {\n    return false;\n  }\n  const statusCode = Number(statusMatch[1]);\n  return statusCode >= 500 && statusCode < 600;\n}\n\n/** @internal */\nexport function createProxyHelpers(args: { proxy: string | undefined }) {\n  const { proxy } = args;\n\n  const resolveProxyUrl = () => {\n    const origin =\n      typeof window !== \"undefined\" &&\n      typeof window.location?.origin === \"string\"\n        ? window.location.origin\n        : typeof location !== \"undefined\" && typeof location.origin === \"string\"\n          ? location.origin\n          : null;\n    if (origin !== null) {\n      return new URL(proxy!, origin).toString();\n    }\n    return Fx.run(\n      Fx.from({\n        ok: () => new URL(proxy!).toString(),\n        err: () => proxy! as string,\n      }).pipe(Fx.recover((fallback) => Fx.succeed(fallback))),\n    );\n  };\n\n  const isAbsoluteUrl = (value: string) => {\n    return Fx.run(\n      Fx.from({\n        ok: () => {\n          new URL(value);\n          return true;\n        },\n        err: () => false as const,\n      }).pipe(Fx.recover((v) => Fx.succeed(v))),\n    );\n  };\n\n  const proxyFetch = async (body: Record<string, unknown>) => {\n    const proxyUrl = await resolveProxyUrl();\n    if (typeof window === \"undefined\" && !(await isAbsoluteUrl(proxyUrl))) {\n      throw new Error(\n        `Cannot call relative proxy URL \\`${proxy!}\\` without a browser origin. ` +\n          \"Pass an absolute proxy URL for server runtimes.\",\n      );\n    }\n\n    const response = await fetch(proxyUrl, {\n      method: \"POST\",\n      headers: { \"Content-Type\": \"application/json\" },\n      credentials: \"include\",\n      body: JSON.stringify(body),\n    });\n    if (!response.ok) {\n      const errorBody = await Fx.run(\n        Fx.from({\n          ok: () => response.json() as Promise<Record<string, unknown>>,\n          err: () => ({}) as Record<string, unknown>,\n        }).pipe(Fx.recover((fallback) => Fx.succeed(fallback))),\n      );\n      if (\n        typeof errorBody === \"object\" &&\n        errorBody !== null &&\n        \"authError\" in errorBody &&\n        typeof (errorBody as Record<string, unknown>).authError === \"object\"\n      ) {\n        throw new ConvexError(\n          (errorBody as Record<string, unknown>).authError as Value,\n        );\n      }\n      throw new Error(\n        ((errorBody as Record<string, unknown>).error as string) ??\n          `Proxy request failed: ${response.status}`,\n      );\n    }\n    return Fx.run(\n      Fx.from({\n        ok: () => response.json(),\n        err: () => new Error(\"Proxy response was not valid JSON\"),\n      }).pipe(Fx.recover((e) => Fx.fatal(e))),\n    );\n  };\n\n  return { isAbsoluteUrl, proxyFetch, resolveProxyUrl };\n}\n"],"mappings":";;;;AAGA,MAAM,wBAAwB;;AAG9B,SAAgB,wBAAwB,OAAyB;AAC/D,QACE,iBAAiB,aAChB,iBAAiB,SAAS,sBAAsB,KAAK,MAAM,WAAW,GAAG;;;AAK9E,SAAgB,6BAA6B,OAAyB;AACpE,KAAI,wBAAwB,MAAM,CAChC,QAAO;AAET,KAAI,EAAE,iBAAiB,OACrB,QAAO;CAET,MAAM,cAAc,MAAM,QAAQ,MAAM,kCAAkC;AAC1E,KAAI,gBAAgB,KAClB,QAAO;CAET,MAAM,aAAa,OAAO,YAAY,GAAG;AACzC,QAAO,cAAc,OAAO,aAAa;;;AAI3C,SAAgB,mBAAmB,MAAqC;CACtE,MAAM,EAAE,UAAU;CAElB,MAAM,wBAAwB;EAC5B,MAAM,SACJ,OAAO,WAAW,eAClB,OAAO,OAAO,UAAU,WAAW,WAC/B,OAAO,SAAS,SAChB,OAAO,aAAa,eAAe,OAAO,SAAS,WAAW,WAC5D,SAAS,SACT;AACR,MAAI,WAAW,KACb,QAAO,IAAI,IAAI,OAAQ,OAAO,CAAC,UAAU;AAE3C,SAAO,GAAG,IACR,GAAG,KAAK;GACN,UAAU,IAAI,IAAI,MAAO,CAAC,UAAU;GACpC,WAAW;GACZ,CAAC,CAAC,KAAK,GAAG,SAAS,aAAa,GAAG,QAAQ,SAAS,CAAC,CAAC,CACxD;;CAGH,MAAM,iBAAiB,UAAkB;AACvC,SAAO,GAAG,IACR,GAAG,KAAK;GACN,UAAU;AACR,QAAI,IAAI,MAAM;AACd,WAAO;;GAET,WAAW;GACZ,CAAC,CAAC,KAAK,GAAG,SAAS,MAAM,GAAG,QAAQ,EAAE,CAAC,CAAC,CAC1C;;CAGH,MAAM,aAAa,OAAO,SAAkC;EAC1D,MAAM,WAAW,MAAM,iBAAiB;AACxC,MAAI,OAAO,WAAW,eAAe,CAAE,MAAM,cAAc,SAAS,CAClE,OAAM,IAAI,MACR,oCAAoC,MAAO,8EAE5C;EAGH,MAAM,WAAW,MAAM,MAAM,UAAU;GACrC,QAAQ;GACR,SAAS,EAAE,gBAAgB,oBAAoB;GAC/C,aAAa;GACb,MAAM,KAAK,UAAU,KAAK;GAC3B,CAAC;AACF,MAAI,CAAC,SAAS,IAAI;GAChB,MAAM,YAAY,MAAM,GAAG,IACzB,GAAG,KAAK;IACN,UAAU,SAAS,MAAM;IACzB,YAAY,EAAE;IACf,CAAC,CAAC,KAAK,GAAG,SAAS,aAAa,GAAG,QAAQ,SAAS,CAAC,CAAC,CACxD;AACD,OACE,OAAO,cAAc,YACrB,cAAc,QACd,eAAe,aACf,OAAQ,UAAsC,cAAc,SAE5D,OAAM,IAAI,YACP,UAAsC,UACxC;AAEH,SAAM,IAAI,MACN,UAAsC,SACtC,yBAAyB,SAAS,SACrC;;AAEH,SAAO,GAAG,IACR,GAAG,KAAK;GACN,UAAU,SAAS,MAAM;GACzB,2BAAW,IAAI,MAAM,oCAAoC;GAC1D,CAAC,CAAC,KAAK,GAAG,SAAS,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC,CACxC;;AAGH,QAAO;EAAE;EAAe;EAAY;EAAiB"}

package/dist/runtime/storage.js

@@ -0,0 +1,37 @@
+import { Fx } from "@robelest/fx";
+
+//#region src/client/runtime/storage.ts
+/** @internal */
+function createStorageHelpers(args) {
+	const { storage, key } = args;
+	const get = async (name) => {
+		if (!storage) return null;
+		return Fx.run(Fx.from({
+			ok: async () => await storage.getItem(key(name)) ?? null,
+			err: (e) => e
+		}).pipe(Fx.inspect((error) => Fx.sync(() => console.error(`[convex-auth] Failed to read ${name} from storage:`, error))), Fx.recover(() => Fx.succeed(null))));
+	};
+	const set = async (name, value) => {
+		if (!storage) return;
+		await Fx.run(Fx.from({
+			ok: () => storage.setItem(key(name), value),
+			err: (e) => e
+		}).pipe(Fx.inspect((error) => Fx.sync(() => console.error(`[convex-auth] Failed to write ${name} to storage:`, error))), Fx.recover(() => Fx.succeed(void 0))));
+	};
+	const remove = async (name) => {
+		if (!storage) return;
+		await Fx.run(Fx.from({
+			ok: () => storage.removeItem(key(name)),
+			err: (e) => e
+		}).pipe(Fx.inspect((error) => Fx.sync(() => console.error(`[convex-auth] Failed to remove ${name} from storage:`, error))), Fx.recover(() => Fx.succeed(void 0))));
+	};
+	return {
+		get,
+		set,
+		remove
+	};
+}
+
+//#endregion
+export { createStorageHelpers };
+//# sourceMappingURL=storage.js.map

package/dist/runtime/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","names":[],"sources":["../../src/client/runtime/storage.ts"],"sourcesContent":["import { Fx } from \"@robelest/fx\";\n\nimport type { Storage } from \"../core/types\";\n\n/** @internal */\nexport function createStorageHelpers(args: {\n  storage: Storage | null;\n  key: (name: string) => string;\n}) {\n  const { storage, key } = args;\n\n  const get = async (name: string): Promise<string | null> => {\n    if (!storage) {\n      return null;\n    }\n    return Fx.run(\n      Fx.from({\n        ok: async () => (await storage.getItem(key(name))) ?? null,\n        err: (e) => e,\n      }).pipe(\n        Fx.inspect((error) =>\n          Fx.sync(() =>\n            console.error(\n              `[convex-auth] Failed to read ${name} from storage:`,\n              error,\n            ),\n          ),\n        ),\n        Fx.recover(() => Fx.succeed(null)),\n      ),\n    );\n  };\n\n  const set = async (name: string, value: string): Promise<void> => {\n    if (!storage) {\n      return;\n    }\n    await Fx.run(\n      Fx.from({\n        ok: () => storage.setItem(key(name), value),\n        err: (e) => e,\n      }).pipe(\n        Fx.inspect((error) =>\n          Fx.sync(() =>\n            console.error(\n              `[convex-auth] Failed to write ${name} to storage:`,\n              error,\n            ),\n          ),\n        ),\n        Fx.recover(() => Fx.succeed(undefined)),\n      ),\n    );\n  };\n\n  const remove = async (name: string): Promise<void> => {\n    if (!storage) {\n      return;\n    }\n    await Fx.run(\n      Fx.from({\n        ok: () => storage.removeItem(key(name)),\n        err: (e) => e,\n      }).pipe(\n        Fx.inspect((error) =>\n          Fx.sync(() =>\n            console.error(\n              `[convex-auth] Failed to remove ${name} from storage:`,\n              error,\n            ),\n          ),\n        ),\n        Fx.recover(() => Fx.succeed(undefined)),\n      ),\n    );\n  };\n\n  return { get, set, remove };\n}\n"],"mappings":";;;;AAKA,SAAgB,qBAAqB,MAGlC;CACD,MAAM,EAAE,SAAS,QAAQ;CAEzB,MAAM,MAAM,OAAO,SAAyC;AAC1D,MAAI,CAAC,QACH,QAAO;AAET,SAAO,GAAG,IACR,GAAG,KAAK;GACN,IAAI,YAAa,MAAM,QAAQ,QAAQ,IAAI,KAAK,CAAC,IAAK;GACtD,MAAM,MAAM;GACb,CAAC,CAAC,KACD,GAAG,SAAS,UACV,GAAG,WACD,QAAQ,MACN,gCAAgC,KAAK,iBACrC,MACD,CACF,CACF,EACD,GAAG,cAAc,GAAG,QAAQ,KAAK,CAAC,CACnC,CACF;;CAGH,MAAM,MAAM,OAAO,MAAc,UAAiC;AAChE,MAAI,CAAC,QACH;AAEF,QAAM,GAAG,IACP,GAAG,KAAK;GACN,UAAU,QAAQ,QAAQ,IAAI,KAAK,EAAE,MAAM;GAC3C,MAAM,MAAM;GACb,CAAC,CAAC,KACD,GAAG,SAAS,UACV,GAAG,WACD,QAAQ,MACN,iCAAiC,KAAK,eACtC,MACD,CACF,CACF,EACD,GAAG,cAAc,GAAG,QAAQ,OAAU,CAAC,CACxC,CACF;;CAGH,MAAM,SAAS,OAAO,SAAgC;AACpD,MAAI,CAAC,QACH;AAEF,QAAM,GAAG,IACP,GAAG,KAAK;GACN,UAAU,QAAQ,WAAW,IAAI,KAAK,CAAC;GACvC,MAAM,MAAM;GACb,CAAC,CAAC,KACD,GAAG,SAAS,UACV,GAAG,WACD,QAAQ,MACN,kCAAkC,KAAK,iBACvC,MACD,CACF,CACF,EACD,GAAG,cAAc,GAAG,QAAQ,OAAU,CAAC,CACxC,CACF;;AAGH,QAAO;EAAE;EAAK;EAAK;EAAQ"}

package/dist/server/auth.d.ts

@@ -1,6 +1,7 @@
 import { AuthAuthorizationConfig, AuthGrant, AuthProviderConfig, AuthRoleId, ConvexAuthConfig, Doc, HasDeviceProvider, HasPasskeyProvider, HasSSO, HasTotpProvider } from "./types.js";
-import { AuthApiRefs } from "../client/index.js";
-import { Auth as Auth$1 } from "./factory.js";
+import { AuthApiRefs } from "../client/core/types.js";
+import "../client/index.js";
+import { Auth as Auth$1 } from "./runtime.js";
 import { UserIdentity } from "convex/server";
 import { GenericId } from "convex/values";
 
@@ -42,20 +43,27 @@ type MemberApiWithAuthorization<TAuthorization extends AuthAuthorizationConfig |
   resolve: (ctx: Parameters<ReturnType<typeof Auth$1>["auth"]["member"]["resolve"]>[0], opts: {
     userId: string;
     groupId: string;
+    ancestry?: boolean;
     roleIds?: AuthRoleId<TAuthorization>[];
     grants?: AuthGrant<TAuthorization>[];
     maxDepth?: number;
   }) => ReturnType<ReturnType<typeof Auth$1>["auth"]["member"]["resolve"]>;
 };
-type AccessApiWithAuthorization<TAuthorization extends AuthAuthorizationConfig | undefined> = {
-  check: (ctx: Parameters<ReturnType<typeof Auth$1>["auth"]["access"]["check"]>[0], opts: {
-    userId: string;
-    groupId: string;
-    grants: AuthGrant<TAuthorization>[];
-    maxDepth?: number;
-  }) => ReturnType<ReturnType<typeof Auth$1>["auth"]["access"]["check"]>;
-};
-/** The base auth API surface, without conditional namespaces. */
+/**
+ * The base auth API surface returned by {@link createAuth}.
+ *
+ * Provides core namespaces — `signIn`, `signOut`, `user`, `session`,
+ * `member`, `invite`, `group`, `key`, and `http` — that are
+ * always available regardless of which providers are configured.
+ * Enterprise namespaces (`sso`, `scim`) are added conditionally by
+ * {@link AuthApi} when an SSO provider is present.
+ *
+ * Use this type when you want to describe code that only depends on the
+ * standard auth surface and should not assume enterprise features exist.
+ *
+ * @typeParam TAuthorization - The authorization config, used to narrow
+ *   role IDs and grant strings on the `member` API.
+ */
 type AuthApiBase<TAuthorization extends AuthAuthorizationConfig | undefined = undefined> = {
   signIn: ReturnType<typeof Auth$1>["signIn"];
   signOut: ReturnType<typeof Auth$1>["signOut"];
@@ -66,10 +74,96 @@ type AuthApiBase<TAuthorization extends AuthAuthorizationConfig | undefined = un
   account: ReturnType<typeof Auth$1>["auth"]["account"];
   group: ReturnType<typeof Auth$1>["auth"]["group"];
   member: MemberApiWithAuthorization<TAuthorization>;
-  access: AccessApiWithAuthorization<TAuthorization>;
   invite: ReturnType<typeof Auth$1>["auth"]["invite"];
   key: ReturnType<typeof Auth$1>["auth"]["key"];
   http: ReturnType<typeof Auth$1>["auth"]["http"];
+  /**
+   * Resolve the current user'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.
+   *
+   * Returns `null` when unauthenticated. Does not throw.
+   *
+   * @param ctx - Convex query, mutation, or action context.
+   * @returns The resolved auth context, or `null`.
+   *
+   * @example fluent-convex middleware
+   * ```ts
+   * const withAuth = convex.createMiddleware(async (ctx, next) => {
+   *   return next({ ...ctx, auth: await auth.resolve(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>;
+  /**
+   * Context enrichment for convex-helpers `customQuery` / `customMutation` /
+   * `customAction`.
+   *
+   * Resolves the current user's identity, active group, membership role,
+   * 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.
+   *
+   * @returns A convex-helpers `Customization` object.
+   *
+   * @example One-time setup in `convex/functions.ts`
+   * ```ts
+   * import { query, mutation, action } from "./_generated/server";
+   * import { customQuery, customMutation, customAction } from "convex-helpers/server/customFunctions";
+   * import { auth } from "./auth";
+   *
+   * export const authQuery = customQuery(query, auth.ctx());
+   * export const authMutation = customMutation(mutation, auth.ctx());
+   * export const authAction = customAction(action, auth.ctx());
+   * ```
+   *
+   * @example Per-function usage
+   * ```ts
+   * import { authQuery } from "./functions";
+   *
+   * 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>;
+    }>;
+  };
+};
+/**
+ * Resolved auth context injected into `ctx.auth` by `auth.ctx()`.
+ *
+ * - `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.
+ */
+type AuthResolvedContext = {
+  /** The authenticated user's document ID. */userId: string; /** The authenticated user's full document. */
+  user: any; /** 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 InternalSsoApi = ReturnType<typeof Auth$1>["auth"]["sso"];
 type PublicSsoAdminApi = {
@@ -148,15 +242,39 @@ type PublicSsoApi = {
 type PublicScimApi = {
   admin: Omit<InternalSsoApi["scim"], "getConfigByToken" | "identity">;
 };
-/** Auth API with enterprise namespaces — present only when `new SSO()` is in providers. */
+/**
+ * Extended auth API that includes enterprise SSO and SCIM namespaces.
+ *
+ * This type is the union of {@link AuthApiBase} plus `sso` (SSO connection
+ * management, OIDC/SAML, domain verification, policies, audit, webhooks)
+ * and `scim` (SCIM provisioning configuration). It is returned by
+ * {@link createAuth} only when `new SSO()` is included in the providers
+ * array; otherwise the narrower {@link AuthApiBase} is returned instead.
+ * Attempting to access `auth.sso` or `auth.scim` without an SSO provider
+ * produces a compile-time error because the return type narrows back to
+ * {@link AuthApiBase}.
+ *
+ * @typeParam TAuthorization - The authorization config, forwarded to
+ *   {@link AuthApiBase} for typed role IDs and grant strings.
+ */
 type AuthApi<TAuthorization extends AuthAuthorizationConfig | undefined = undefined> = AuthApiBase<TAuthorization> & {
   sso: PublicSsoApi;
   scim: PublicScimApi;
 };
 /**
- * The return type of `createAuth`. Conditional namespaces:
- * - `auth.sso` and `auth.scim` — only when `new SSO()` is in providers
- * - `auth.clientApi` — typed API refs for the client SDK with capabilities
+ * The return type of {@link createAuth}.
+ *
+ * Resolves to {@link AuthApi} (with `sso` and `scim` namespaces) when
+ * `new SSO()` is present in the providers array, or to the narrower
+ * {@link AuthApiBase} otherwise. This conditional type ensures that
+ * enterprise-only APIs are only accessible when the SSO provider is
+ * configured, producing a compile-time error if you try to access
+ * `auth.sso` without it.
+ * This lets application code keep a single `createAuth()` call while still
+ * getting provider-aware typing on the resulting API object.
+ *
+ * @typeParam P - The tuple of provider configs passed to `createAuth`.
+ * @typeParam TAuthorization - Optional authorization config for typed roles/grants.
  */
 type ConvexAuthResult<P extends AuthProviderConfig[], TAuthorization extends AuthAuthorizationConfig | undefined = undefined> = HasSSO<P> extends true ? AuthApi<TAuthorization> : AuthApiBase<TAuthorization>;
 /**
@@ -170,28 +288,55 @@ type ConvexAuthResult<P extends AuthProviderConfig[], TAuthorization extends Aut
  *
  * // Frontend
  * import type { auth } from "../convex/auth";
- * import type { InferClientApi } from "@robelest/convex-auth/component";
+ * import type { InferClientApi } from "@robelest/convex-auth/server";
  * const c = client<InferClientApi<typeof auth>>({ convex, api: api.auth });
  * ```
- */
-type InferClientApi<T> = T extends ConvexAuthResult<infer P> ? AuthApiRefs<HasPasskeyProvider<P>, HasTotpProvider<P>, HasDeviceProvider<P>> : AuthApiRefs;
-/**
- * Create an auth API object.
  *
- * When `new SSO()` is included in providers, `auth.sso` and `auth.scim`
- * are available on the returned object. Without it, those namespaces are
- * absent and accessing them is a TypeScript compile error.
+ * @typeParam T - A ConvexAuthResult to extract the client API from.
  */
+type InferClientApi<T> = T extends ConvexAuthResult<infer P> ? AuthApiRefs<HasPasskeyProvider<P>, HasTotpProvider<P>, HasDeviceProvider<P>> : AuthApiRefs;
 declare function createAuth<P extends AuthProviderConfig[], TAuthorization extends AuthAuthorizationConfig | undefined = undefined>(component: ConvexAuthConfig["component"], config: Omit<AuthConfig, "providers" | "authorization"> & {
   providers: P;
   authorization?: TAuthorization;
 }): ConvexAuthResult<P, TAuthorization>;
+/** Canonical user document type exposed by Convex Auth. */
 type UserDoc = Doc<"User">;
+/**
+ * Configuration for {@link AuthCtx} context enrichment.
+ *
+ * @typeParam TResolve - Extra fields returned from `resolve()` and merged into
+ *   the resulting `ctx.auth` object.
+ */
 type AuthCtxConfig<TResolve extends Record<string, unknown> = Record<string, never>> = {
-  optional?: boolean;
+  /** Allow unauthenticated callers and return `userId: null` / `user: null`. */optional?: boolean;
+  /**
+   * Attach additional derived fields to the auth context after the user is resolved.
+   */
   resolve?: (ctx: any, user: UserDoc) => Promise<TResolve> | TResolve;
 };
-/** Overload: optional auth */
+/**
+ * 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.
+ *
+ * @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;
 }): {
@@ -207,7 +352,29 @@ declare function AuthCtx<TResolve extends Record<string, unknown> = Record<strin
     args: {};
   }>;
 };
-/** Overload: required auth (default) */
+/**
+ * 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`.
+ *
+ * @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<{
@@ -221,6 +388,29 @@ declare function AuthCtx<TResolve extends Record<string, unknown> = Record<strin
     args: {};
   }>;
 };
+/**
+ * Extract the resolved `auth` context type from an {@link AuthCtx} instance.
+ *
+ * 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.
+ *
+ * @typeParam T - An `AuthCtx` return value (must have an `input` method
+ *   that returns `{ ctx: { auth: ... } }`).
+ *
+ * @example
+ * ```ts
+ * const authCtx = AuthCtx(auth, {
+ *   resolve: async (ctx, user) => ({ orgId: user.orgId }),
+ * });
+ * type Auth = InferAuth<typeof authCtx>;
+ * // Auth = { userId: Id<"User">; user: UserDoc; getUserIdentity: ...; orgId: string }
+ * ```
+ *
+ * @see {@link createAuth}
+ */
 type InferAuth<T extends {
   input: (...args: any[]) => Promise<{
     ctx: {
@@ -229,5 +419,5 @@ type InferAuth<T extends {
   }>;
 }> = Awaited<ReturnType<T["input"]>>["ctx"]["auth"];
 //#endregion
-export { AuthApi, AuthApiBase, AuthConfig, AuthCtx, AuthCtxConfig, ConvexAuthResult, InferAuth, InferClientApi, UserDoc, createAuth };
+export { AuthApi, AuthApiBase, AuthConfig, AuthCtx, AuthCtxConfig, AuthResolvedContext, ConvexAuthResult, InferAuth, InferClientApi, UserDoc, createAuth };
 //# sourceMappingURL=auth.d.ts.map

package/dist/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/server/auth.js

@@ -1,5 +1,6 @@
-import { AuthError, Fx } from "./fx.js";
-import { Auth } from "./factory.js";
+import { AuthError } from "./authError.js";
+import { Auth } from "./runtime.js";
+import { Fx } from "@robelest/fx";
 
 //#region src/server/auth.ts
 /**
@@ -8,7 +9,61 @@ import { Auth } from "./factory.js";
 * When `new SSO()` is included in providers, `auth.sso` and `auth.scim`
 * are available on the returned object. Without it, those namespaces are
 * absent and accessing them is a TypeScript compile error.
+*
+* @param component - The installed auth component reference from
+*   `components.auth` in your Convex app definition.
+* @param config - Auth configuration including `providers` and optional
+*   `authorization`. All fields from {@link AuthConfig} are accepted
+*   except `component` (passed as the first argument).
+* @returns A {@link ConvexAuthResult} object — either {@link AuthApi}
+*   (with `sso`/`scim`) or {@link AuthApiBase}, depending on whether
+*   an SSO provider is present.
+*
+* @example
+* ```ts
+* export const auth = createAuth(components.auth, {
+*   providers: [password(), google()],
+*   authorization: { roles },
+* });
+* ```
+*
+* @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
 */
+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;
+		}
+	}
+	return {
+		userId,
+		user,
+		groupId,
+		role,
+		grants
+	};
+}
 function createAuth(component, config) {
 	const authResult = Auth({
 		...config,
@@ -105,7 +160,6 @@ function createAuth(component, config) {
 		account: authResult.auth.account,
 		group: authResult.auth.group,
 		member: authResult.auth.member,
-		access: authResult.auth.access,
 		invite: authResult.auth.invite,
 		key: authResult.auth.key,
 		sso: publicSso,
@@ -114,7 +168,17 @@ function createAuth(component, config) {
 			get: scimApi.get,
 			validate: scimApi.validate
 		} },
-		http: authResult.auth.http
+		http: authResult.auth.http,
+		resolve: (ctx) => resolveAuthContext(authResult.auth, ctx),
+		ctx: () => ({
+			args: {},
+			input: async (ctx) => {
+				return {
+					ctx: { auth: await resolveAuthContext(authResult.auth, ctx) },
+					args: {}
+				};
+			}
+		})
 	};
 }
 function AuthCtx(auth, config) {