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

package/src/server/auth.ts

@@ -8,9 +8,9 @@ import type { UserIdentity } from "convex/server";
 import type { GenericId } from "convex/values";
 
 import type { AuthApiRefs } from "../client/index";
-import { Auth as AuthFactory } from "./factory";
-import { Fx } from "./fx";
-import { AuthError } from "./fx";
+import { Auth as AuthFactory } from "./runtime";
+import { Fx } from "@robelest/fx";
+import { AuthError } from "./authError";
 import type { Doc } from "./types";
 import type {
   AuthAuthorizationConfig,
@@ -84,6 +84,7 @@ type MemberApiWithAuthorization<
     opts: {
       userId: string;
       groupId: string;
+      ancestry?: boolean;
       roleIds?: AuthRoleId<TAuthorization>[];
       grants?: AuthGrant<TAuthorization>[];
       maxDepth?: number;
@@ -91,23 +92,22 @@ type MemberApiWithAuthorization<
   ) => ReturnType<ReturnType<typeof AuthFactory>["auth"]["member"]["resolve"]>;
 };
 
-type AccessApiWithAuthorization<
-  TAuthorization extends AuthAuthorizationConfig | undefined,
-> = {
-  check: (
-    ctx: Parameters<
-      ReturnType<typeof AuthFactory>["auth"]["access"]["check"]
-    >[0],
-    opts: {
-      userId: string;
-      groupId: string;
-      grants: AuthGrant<TAuthorization>[];
-      maxDepth?: number;
-    },
-  ) => ReturnType<ReturnType<typeof AuthFactory>["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.
+ */
 export type AuthApiBase<
   TAuthorization extends AuthAuthorizationConfig | undefined = undefined,
 > = {
@@ -120,10 +120,100 @@ export type AuthApiBase<
   account: ReturnType<typeof AuthFactory>["auth"]["account"];
   group: ReturnType<typeof AuthFactory>["auth"]["group"];
   member: MemberApiWithAuthorization<TAuthorization>;
-  access: AccessApiWithAuthorization<TAuthorization>;
   invite: ReturnType<typeof AuthFactory>["auth"]["invite"];
   key: ReturnType<typeof AuthFactory>["auth"]["key"];
   http: ReturnType<typeof AuthFactory>["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.
+ */
+export 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 AuthFactory>["auth"]["sso"];
@@ -208,7 +298,21 @@ 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.
+ */
 export type AuthApi<
   TAuthorization extends AuthAuthorizationConfig | undefined = undefined,
 > = AuthApiBase<TAuthorization> & {
@@ -217,9 +321,19 @@ export type AuthApi<
 };
 
 /**
- * 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.
  */
 export type ConvexAuthResult<
   P extends AuthProviderConfig[],
@@ -240,9 +354,11 @@ export type ConvexAuthResult<
  *
  * // 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 });
  * ```
+ *
+ * @typeParam T - A ConvexAuthResult to extract the client API from.
  */
 export type InferClientApi<T> =
   T extends ConvexAuthResult<infer P>
@@ -266,7 +382,58 @@ export type AuthLike = Pick<AuthApiBase, "user">;
  * 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}
+ */
+
+// ---------------------------------------------------------------------------
+// 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: any, 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;
+    }
+  }
+  return { userId, user, groupId, role, grants };
+}
+
 export function createAuth<
   P extends AuthProviderConfig[],
   TAuthorization extends AuthAuthorizationConfig | undefined = undefined,
@@ -450,7 +617,6 @@ export function createAuth<
     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,
@@ -462,6 +628,16 @@ export function createAuth<
       },
     },
     http: authResult.auth.http,
+
+    resolve: (ctx: any) => resolveAuthContext(authResult.auth, ctx),
+
+    ctx: () => ({
+      args: {},
+      input: async (ctx: any) => {
+        const authCtx = await resolveAuthContext(authResult.auth, ctx);
+        return { ctx: { auth: authCtx }, args: {} };
+      },
+    }),
   } as unknown as ConvexAuthResult<P, TAuthorization>;
 }
 
@@ -469,16 +645,49 @@ export function createAuth<
 // AuthCtx — ctx enrichment for customQuery / customMutation
 // ============================================================================
 
+/** Canonical user document type exposed by Convex Auth. */
 export type UserDoc = Doc<"User">;
 
+/**
+ * Configuration for {@link AuthCtx} context enrichment.
+ *
+ * @typeParam TResolve - Extra fields returned from `resolve()` and merged into
+ *   the resulting `ctx.auth` object.
+ */
 export type AuthCtxConfig<
   TResolve extends Record<string, unknown> = Record<string, never>,
 > = {
+  /** 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}
+ */
 export function AuthCtx<
   TResolve extends Record<string, unknown> = Record<string, never>,
 >(
@@ -501,7 +710,29 @@ export function AuthCtx<
     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}
+ */
 export function AuthCtx<
   TResolve extends Record<string, unknown> = Record<string, never>,
 >(
@@ -588,6 +819,29 @@ export function AuthCtx(auth: AuthLike, config?: AuthCtxConfig<any>) {
   };
 }
 
+/**
+ * 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}
+ */
 export type InferAuth<
   T extends { input: (...args: any[]) => Promise<{ ctx: { auth: any } }> },
 > = Awaited<ReturnType<T["input"]>>["ctx"]["auth"];

package/src/server/authError.ts

@@ -0,0 +1,44 @@
+import { Cv } from "@robelest/fx/convex";
+import type { ConvexError } from "convex/values";
+
+import { AUTH_ERRORS } from "./errors";
+import type { AuthErrorCode } from "./errors";
+
+/**
+ * Typed error for the Fx error channel.
+ *
+ * Use with `Fx.fail(new AuthError("CODE"))` in pipelines.
+ * At Convex boundaries, {@link toConvexError} converts these to `ConvexError`.
+ */
+export class AuthError extends Error {
+  /**
+   * Discriminant tag for error channel matching.
+   * @readonly
+   */
+  readonly _tag = "AuthError" as const;
+
+  constructor(
+    /**
+     * Machine-readable error code.
+     * @readonly
+     */
+    readonly code: AuthErrorCode,
+    message?: string,
+    /**
+     * Optional structured context for diagnostics.
+     * @readonly
+     */
+    readonly context?: Record<string, unknown>,
+  ) {
+    super(message ?? AUTH_ERRORS[code]);
+  }
+
+  /** Convert to the `ConvexError` shape the Convex runtime expects. */
+  toConvexError(): ConvexError<{ code: AuthErrorCode; message: string }> {
+    return Cv.error({
+      code: this.code,
+      message: this.message,
+      ...this.context,
+    });
+  }
+}