@robelest/convex-auth 0.0.4-preview.2 → 0.0.4-preview.21

package/dist/server/auth.d.ts

@@ -1,406 +1,343 @@
-import { Doc, KeyDoc } from "./implementation/types.js";
-import { Auth as Auth$2 } from "./implementation/index.js";
-import { ComponentApi } from "../component/_generated/component.js";
-import { AuthProviderConfig, ConvexAuthConfig, CorsConfig, HttpKeyContext, KeyScope, ScopeChecker, UserOrderBy, UserWhere } from "./types.js";
-import * as convex_server0 from "convex/server";
+import { AuthAuthorizationConfig, AuthGrant, AuthProviderConfig, AuthRoleId, ConvexAuthConfig, Doc, HasDeviceProvider, HasPasskeyProvider, HasSSO, HasTotpProvider } from "./types.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";
 
 //#region src/server/auth.d.ts
 /**
- * Config for the Auth class. Extends the standard auth config
+ * Config for auth setup. Extends the standard auth config
  * minus `component` (which is passed as the first constructor argument).
- *
- * When `email` is configured, the library auto-registers a
- * magic link provider (`id: "email"`) for user-facing sign-in.
  */
-type AuthClassConfig = Omit<ConvexAuthConfig, "component">;
+type AuthConfig = Omit<ConvexAuthConfig, "component">;
+type MemberApiWithAuthorization<TAuthorization extends AuthAuthorizationConfig | undefined> = Omit<ReturnType<typeof Auth$1>["auth"]["member"], "create" | "list" | "update" | "resolve"> & {
+  create: (ctx: Parameters<ReturnType<typeof Auth$1>["auth"]["member"]["create"]>[0], data: {
+    groupId: string;
+    userId: string;
+    roleIds?: AuthRoleId<TAuthorization>[];
+    status?: string;
+    extend?: Record<string, unknown>;
+  }) => Promise<{
+    ok: true;
+    memberId: string;
+  }>;
+  list: (ctx: Parameters<ReturnType<typeof Auth$1>["auth"]["member"]["list"]>[0], opts?: {
+    where?: {
+      groupId?: string;
+      userId?: string;
+      roleId?: AuthRoleId<TAuthorization>;
+      status?: string;
+    };
+    limit?: number;
+    cursor?: string | null;
+    orderBy?: "_creationTime" | "status";
+    order?: "asc" | "desc";
+  }) => ReturnType<ReturnType<typeof Auth$1>["auth"]["member"]["list"]>;
+  update: (ctx: Parameters<ReturnType<typeof Auth$1>["auth"]["member"]["update"]>[0], memberId: string, data: Record<string, unknown> & {
+    roleIds?: AuthRoleId<TAuthorization>[];
+  }) => Promise<{
+    ok: true;
+    memberId: string;
+  }>;
+  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"]>;
+};
 /**
- * Main entry point for Convex Auth. Instantiate with your component
- * reference and config to get all the exports you need.
+ * The base auth API surface returned by {@link createAuth}.
  *
- * ```ts
- * export const auth = new Auth(components.auth, {
- *   providers: [google, password],
- *   email: {
- *     from: "My App <noreply@example.com>",
- *     send: (ctx, params) => resend.sendEmail(ctx, params),
- *   },
- * });
- * export const { signIn, signOut, store } = auth;
- * ```
+ * 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.
  */
-declare class Auth {
-  /** The inner `auth` helper object from AuthFactory() */
-  private readonly _auth;
-  /** The signIn action — export this from your convex/auth.ts */
-  readonly signIn: ReturnType<typeof Auth$2>["signIn"];
-  /** The signOut action — export this from your convex/auth.ts */
-  readonly signOut: ReturnType<typeof Auth$2>["signOut"];
-  /** The store internal mutation — export this from your convex/auth.ts */
-  readonly store: ReturnType<typeof Auth$2>["store"];
-  /** User helpers: `.current(ctx)`, `.require(ctx)`, `.get(ctx, userId)`, `.patch(ctx, userId, data)`, `.viewer(ctx)`, `.group.list(ctx, ...)`, `.group.get(ctx, ...)` */
-  get user(): {
-    current: (ctx: {
-      auth: convex_server0.Auth;
-    }) => Promise<GenericId<"user"> | null>;
-    require: (ctx: {
-      auth: convex_server0.Auth;
-    }) => Promise<GenericId<"user">>;
-    get: (ctx: Pick<convex_server0.GenericActionCtx<convex_server0.GenericDataModel>, "runQuery">, userId: string) => Promise<any>;
-    list: (ctx: Pick<convex_server0.GenericActionCtx<convex_server0.GenericDataModel>, "runQuery">, opts?: {
-      where?: UserWhere;
-      limit?: number;
-      cursor?: string | null;
-      orderBy?: UserOrderBy;
-      order?: "asc" | "desc";
-    }) => Promise<any>;
-    viewer: (ctx: Pick<convex_server0.GenericActionCtx<convex_server0.GenericDataModel>, "runQuery"> & {
-      auth: convex_server0.Auth;
-    }) => Promise<any>;
-    patch: (ctx: Pick<convex_server0.GenericActionCtx<convex_server0.GenericDataModel>, "runQuery" | "runMutation">, userId: string, data: Record<string, unknown>) => Promise<void>;
-    group: {
-      list: (ctx: Pick<convex_server0.GenericActionCtx<convex_server0.GenericDataModel>, "runQuery">, opts: {
-        userId: string;
-        limit?: number;
-        cursor?: string | null;
-        order?: "asc" | "desc";
-      }) => Promise<any>;
-      get: (ctx: Pick<convex_server0.GenericActionCtx<convex_server0.GenericDataModel>, "runQuery">, opts: {
-        userId: string;
-        groupId: string;
-      }) => Promise<any>;
-    };
-  };
-  /** Session helpers: `.current(ctx)`, `.invalidate(ctx, { userId, except? })` */
-  get session(): {
-    current: (ctx: {
-      auth: convex_server0.Auth;
-    }) => Promise<GenericId<"session"> | null>;
-    invalidate: <DataModel extends convex_server0.GenericDataModel>(ctx: convex_server0.GenericActionCtx<DataModel>, args: {
-      userId: GenericId<"user">;
-      except?: GenericId<"session">[];
-    }) => Promise<void>;
-  };
-  /** Provider helpers: `.signIn(ctx, provider, args)` */
-  get provider(): {
-    signIn: <DataModel extends convex_server0.GenericDataModel>(ctx: convex_server0.GenericActionCtx<DataModel>, provider: AuthProviderConfig, args: {
-      accountId?: GenericId<"account">;
-      params?: Record<string, unknown>;
-    }) => Promise<{
-      userId: GenericId<"user">;
-      sessionId: GenericId<"session">;
-    } | null>;
-  };
-  /** Account helpers: `.create(ctx, args)`, `.get(ctx, args)`, `.update(ctx, args)` */
-  get account(): {
-    create: <DataModel extends convex_server0.GenericDataModel>(ctx: convex_server0.GenericActionCtx<DataModel>, args: {
-      provider: string;
-      account: {
-        id: string;
-        secret?: string;
-      };
-      profile: Record<string, unknown>;
-      shouldLinkViaEmail?: boolean;
-      shouldLinkViaPhone?: boolean;
-    }) => Promise<{
-      account: Doc<"account">;
-      user: Doc<"user">;
-    }>;
-    get: <DataModel extends convex_server0.GenericDataModel>(ctx: convex_server0.GenericActionCtx<DataModel>, args: {
-      provider: string;
-      account: {
-        id: string;
-        secret?: string;
+type AuthApiBase<TAuthorization extends AuthAuthorizationConfig | undefined = undefined> = {
+  signIn: ReturnType<typeof Auth$1>["signIn"];
+  signOut: ReturnType<typeof Auth$1>["signOut"];
+  store: ReturnType<typeof Auth$1>["store"];
+  user: ReturnType<typeof Auth$1>["auth"]["user"];
+  session: ReturnType<typeof Auth$1>["auth"]["session"];
+  provider: ReturnType<typeof Auth$1>["auth"]["provider"];
+  account: ReturnType<typeof Auth$1>["auth"]["account"];
+  group: ReturnType<typeof Auth$1>["auth"]["group"];
+  member: MemberApiWithAuthorization<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;
       };
-    }) => Promise<{
-      account: Doc<"account">;
-      user: Doc<"user">;
+      args: Record<string, never>;
     }>;
-    update: <DataModel extends convex_server0.GenericDataModel>(ctx: convex_server0.GenericActionCtx<DataModel>, args: {
-      provider: string;
-      account: {
-        id: string;
-        secret: string;
-      };
-    }) => Promise<void>;
   };
-  /** Group helpers: `.create(ctx, ...)`, `.get(ctx, id)`, `.list(ctx, ...)`, `.update(ctx, ...)`, `.delete(ctx, id)`, `.member.*` */
-  get group(): {
-    create: (ctx: Pick<convex_server0.GenericActionCtx<convex_server0.GenericDataModel>, "runQuery" | "runMutation">, data: {
-      name: string;
-      slug?: string;
-      type?: string;
-      parentGroupId?: string;
-      tags?: Array<{
-        key: string;
-        value: string;
+};
+/**
+ * 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 = {
+  connection: InternalSsoApi["connection"] & {
+    domain: {
+      list: InternalSsoApi["domain"]["list"];
+      validate: InternalSsoApi["domain"]["validate"];
+      set: (ctx: Parameters<InternalSsoApi["connection"]["create"]>[0], enterpriseId: string, domains: Array<{
+        domain: string;
+        isPrimary?: boolean;
+      }>) => Promise<{
+        ok: true;
+        enterpriseId: string;
+        domains: Array<{
+          domainId: string;
+          domain: string;
+          isPrimary: boolean;
+          verified: boolean;
+          verifiedAt: number | null;
+        }>;
       }>;
-      extend?: Record<string, unknown>;
-    }) => Promise<string>;
-    get: (ctx: Pick<convex_server0.GenericActionCtx<convex_server0.GenericDataModel>, "runQuery">, groupId: string) => Promise<any>;
-    list: (ctx: Pick<convex_server0.GenericActionCtx<convex_server0.GenericDataModel>, "runQuery">, opts?: {
-      where?: {
-        slug?: string;
-        type?: string;
-        parentGroupId?: string;
-        name?: string;
-        isRoot?: boolean;
-        tagsAll?: Array<{
-          key: string;
-          value: string;
+      verification: {
+        request: (ctx: Parameters<InternalSsoApi["connection"]["create"]>[0], args: {
+          enterpriseId: string;
+          domain: string;
+        }) => Promise<{
+          ok: true;
+          enterpriseId: string;
+          domain: string;
+          requestedAt: number;
+          expiresAt: number;
+          challenge: {
+            recordType: "TXT";
+            recordName: string;
+            recordValue: string;
+          };
         }>;
-        tagsAny?: Array<{
-          key: string;
-          value: string;
+        confirm: (ctx: Parameters<InternalSsoApi["connection"]["create"]>[0], args: {
+          enterpriseId: string;
+          domain: string;
+        }) => Promise<{
+          ok: boolean;
+          enterpriseId: string;
+          domain: string;
+          verifiedAt?: number;
+          checks: Array<{
+            name: string;
+            ok: boolean;
+            message?: string;
+          }>;
         }>;
       };
-      limit?: number;
-      cursor?: string | null;
-      orderBy?: "_creationTime" | "name" | "slug" | "type";
-      order?: "asc" | "desc";
-    }) => Promise<any>;
-    update: (ctx: Pick<convex_server0.GenericActionCtx<convex_server0.GenericDataModel>, "runQuery" | "runMutation">, groupId: string, data: Record<string, unknown>) => Promise<void>;
-    delete: (ctx: Pick<convex_server0.GenericActionCtx<convex_server0.GenericDataModel>, "runQuery" | "runMutation">, groupId: string) => Promise<void>;
-    member: {
-      add: (ctx: Pick<convex_server0.GenericActionCtx<convex_server0.GenericDataModel>, "runQuery" | "runMutation">, data: {
-        groupId: string;
-        userId: string;
-        role?: string;
-        status?: string;
-        extend?: Record<string, unknown>;
-      }) => Promise<string>;
-      get: (ctx: Pick<convex_server0.GenericActionCtx<convex_server0.GenericDataModel>, "runQuery">, memberId: string) => Promise<any>;
-      list: (ctx: Pick<convex_server0.GenericActionCtx<convex_server0.GenericDataModel>, "runQuery">, opts?: {
-        where?: {
-          groupId?: string;
-          userId?: string;
-          role?: string;
-          status?: string;
-        };
-        limit?: number;
-        cursor?: string | null;
-        orderBy?: "_creationTime" | "role" | "status";
-        order?: "asc" | "desc";
-      }) => Promise<any>;
-      remove: (ctx: Pick<convex_server0.GenericActionCtx<convex_server0.GenericDataModel>, "runQuery" | "runMutation">, memberId: string) => Promise<void>;
-      update: (ctx: Pick<convex_server0.GenericActionCtx<convex_server0.GenericDataModel>, "runQuery" | "runMutation">, memberId: string, data: Record<string, unknown>) => Promise<void>;
     };
   };
-  /** Invite helpers: `.create(ctx, ...)`, `.get(ctx, id)`, `.list(ctx, ...)`, `.accept(ctx, ...)`, `.revoke(ctx, id)` */
-  get invite(): {
-    create: (ctx: Pick<convex_server0.GenericActionCtx<convex_server0.GenericDataModel>, "runQuery" | "runMutation">, data: {
-      groupId?: string;
-      invitedByUserId?: string;
-      email?: string;
-      tokenHash: string;
-      role?: string;
-      status: "pending" | "accepted" | "revoked" | "expired";
-      expiresTime?: number;
-      extend?: Record<string, unknown>;
-    }) => Promise<string>;
-    get: (ctx: Pick<convex_server0.GenericActionCtx<convex_server0.GenericDataModel>, "runQuery">, inviteId: string) => Promise<any>;
-    list: (ctx: Pick<convex_server0.GenericActionCtx<convex_server0.GenericDataModel>, "runQuery">, opts?: {
-      where?: {
-        tokenHash?: string;
-        groupId?: string;
-        status?: "pending" | "accepted" | "revoked" | "expired";
-        email?: string;
-        invitedByUserId?: string;
-        role?: string;
-        acceptedByUserId?: string;
-      };
-      limit?: number;
-      cursor?: string | null;
-      orderBy?: "_creationTime" | "status" | "email" | "expiresTime" | "acceptedTime";
-      order?: "asc" | "desc";
-    }) => Promise<any>;
-    accept: (ctx: Pick<convex_server0.GenericActionCtx<convex_server0.GenericDataModel>, "runQuery" | "runMutation">, inviteId: string, acceptedByUserId?: string) => Promise<void>;
-    revoke: (ctx: Pick<convex_server0.GenericActionCtx<convex_server0.GenericDataModel>, "runQuery" | "runMutation">, inviteId: string) => Promise<void>;
-  };
-  /** Passkey helpers: `.list(ctx, { userId })`, `.rename(ctx, id, name)`, `.remove(ctx, id)` */
-  get passkey(): {
-    list: (ctx: Pick<convex_server0.GenericActionCtx<convex_server0.GenericDataModel>, "runQuery">, opts: {
-      userId: string;
-    }) => Promise<any>;
-    rename: (ctx: Pick<convex_server0.GenericActionCtx<convex_server0.GenericDataModel>, "runQuery" | "runMutation">, passkeyId: string, name: string) => Promise<void>;
-    remove: (ctx: Pick<convex_server0.GenericActionCtx<convex_server0.GenericDataModel>, "runQuery" | "runMutation">, passkeyId: string) => Promise<void>;
-  };
-  /** TOTP helpers: `.list(ctx, { userId })`, `.remove(ctx, id)` */
-  get totp(): {
-    list: (ctx: Pick<convex_server0.GenericActionCtx<convex_server0.GenericDataModel>, "runQuery">, opts: {
-      userId: string;
-    }) => Promise<any>;
-    remove: (ctx: Pick<convex_server0.GenericActionCtx<convex_server0.GenericDataModel>, "runQuery" | "runMutation">, totpId: string) => Promise<void>;
-  };
-  /** API key helpers: `.create(ctx, ...)`, `.verify(ctx, rawKey)`, `.list(ctx, ...)`, `.get(ctx, id)`, `.update(ctx, ...)`, `.revoke(ctx, id)`, `.remove(ctx, id)` */
-  get key(): {
-    create: (ctx: Pick<convex_server0.GenericActionCtx<convex_server0.GenericDataModel>, "runQuery" | "runMutation">, opts: {
-      userId: string;
-      name: string;
-      scopes: KeyScope[];
-      rateLimit?: {
-        maxRequests: number;
-        windowMs: number;
-      };
-      expiresAt?: number;
-    }) => Promise<{
-      keyId: string;
-      raw: string;
-    }>;
-    verify: (ctx: Pick<convex_server0.GenericActionCtx<convex_server0.GenericDataModel>, "runQuery" | "runMutation">, rawKey: string) => Promise<{
-      userId: string;
-      keyId: string;
-      scopes: ScopeChecker;
-    }>;
-    list: (ctx: Pick<convex_server0.GenericActionCtx<convex_server0.GenericDataModel>, "runQuery">, opts?: {
-      where?: {
-        userId?: string;
-        revoked?: boolean;
-        name?: string;
-        prefix?: string;
-      };
-      limit?: number;
-      cursor?: string | null;
-      orderBy?: "_creationTime" | "name" | "lastUsedAt" | "expiresAt" | "revoked";
-      order?: "asc" | "desc";
-    }) => Promise<any>;
-    get: (ctx: Pick<convex_server0.GenericActionCtx<convex_server0.GenericDataModel>, "runQuery">, keyId: string) => Promise<KeyDoc | null>;
-    update: (ctx: Pick<convex_server0.GenericActionCtx<convex_server0.GenericDataModel>, "runQuery" | "runMutation">, keyId: string, data: {
-      name?: string;
-      scopes?: KeyScope[];
-      rateLimit?: {
-        maxRequests: number;
-        windowMs: number;
-      };
-    }) => Promise<void>;
-    revoke: (ctx: Pick<convex_server0.GenericActionCtx<convex_server0.GenericDataModel>, "runQuery" | "runMutation">, keyId: string) => Promise<void>;
-    remove: (ctx: Pick<convex_server0.GenericActionCtx<convex_server0.GenericDataModel>, "runQuery" | "runMutation">, keyId: string) => Promise<void>;
+  oidc: Omit<InternalSsoApi["oidc"], "signIn">;
+  saml: Omit<InternalSsoApi["saml"], "metadata">;
+  policy: InternalSsoApi["policy"];
+  audit: {
+    list: InternalSsoApi["audit"]["list"];
   };
-  /**
-   * @param component - The auth component reference from `components.auth`.
-   * @param config - Auth configuration (providers, email transport, session, JWT, callbacks).
-   */
-  constructor(component: ComponentApi, config: AuthClassConfig);
-  /** HTTP namespace — route registration and Bearer-authenticated endpoints. */
-  get http(): {
-    add: (http: convex_server0.HttpRouter) => void;
-    action: (handler: (ctx: convex_server0.GenericActionCtx<convex_server0.GenericDataModel> & HttpKeyContext, request: Request) => Promise<Response | Record<string, unknown>>, options?: {
-      scope?: {
-        resource: string;
-        action: string;
-      };
-      cors?: CorsConfig;
-    }) => convex_server0.PublicHttpAction;
-    route: (http: convex_server0.HttpRouter, routeConfig: {
-      path: string;
-      method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
-      handler: (ctx: convex_server0.GenericActionCtx<convex_server0.GenericDataModel> & HttpKeyContext, request: Request) => Promise<Response | Record<string, unknown>>;
-      scope?: {
-        resource: string;
-        action: string;
-      };
-      cors?: CorsConfig;
-    }) => void;
+  webhook: {
+    endpoint: InternalSsoApi["webhook"]["endpoint"];
+    delivery: {
+      list: InternalSsoApi["webhook"]["delivery"]["list"];
+    };
   };
-}
+};
+type PublicSsoClientApi = {
+  signIn: InternalSsoApi["oidc"]["signIn"];
+  metadata: InternalSsoApi["saml"]["metadata"];
+};
+type PublicSsoApi = {
+  admin: PublicSsoAdminApi;
+  client: PublicSsoClientApi;
+};
+type PublicScimApi = {
+  admin: Omit<InternalSsoApi["scim"], "getConfigByToken" | "identity">;
+};
 /**
- * The shape of a user document from the auth component's `user` table.
+ * Extended auth API that includes enterprise SSO and SCIM namespaces.
  *
- * Includes system fields (`_id`, `_creationTime`) plus the schema fields
- * (`name`, `email`, `image`, `extend`, etc.).
- */
-type UserDoc = Doc<"user">;
-/**
- * Configuration for auth context enrichment.
+ * 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 TResolve - The shape returned by the `resolve` callback.
- *   Inferred automatically — you usually don't need to supply this manually.
+ * @typeParam TAuthorization - The authorization config, forwarded to
+ *   {@link AuthApiBase} for typed role IDs and grant strings.
  */
-type AuthCtxConfig<TResolve extends Record<string, unknown> = Record<string, never>> = {
-  /**
-   * When `true`, unauthenticated requests set `ctx.auth.userId` and
-   * `ctx.auth.user` to `null` instead of throwing.
-   *
-   * @default false
-   */
-  optional?: boolean;
-  /**
-   * Resolve additional context after authentication succeeds (e.g.
-   * group/role for multi-tenant apps). The returned object is spread
-   * into `ctx.auth`.
-   */
-  resolve?: (ctx: any, user: UserDoc) => Promise<TResolve> | TResolve;
+type AuthApi<TAuthorization extends AuthAuthorizationConfig | undefined = undefined> = AuthApiBase<TAuthorization> & {
+  sso: PublicSsoApi;
+  scim: PublicScimApi;
 };
 /**
- * Create a `convex-helpers`–compatible customization object that
- * enriches `ctx.auth` with the authenticated user's data.
- *
- * Standalone function (not a class method) because Convex's bundler
- * can trace `export const x = fn(instance)` but not `instance.method()`.
- *
- * ### Basic usage (with `convex-helpers`)
- *
- * ```ts
- * // convex/functions.ts
- * import { customQuery, customMutation } from "convex-helpers/server/customFunctions";
- * import { query as rawQuery, mutation as rawMutation } from "./_generated/server";
- * import { AuthCtx } from "\@robelest/convex-auth/component";
- * import { auth } from "./auth";
+ * The return type of {@link createAuth}.
  *
- * const authCtx = AuthCtx(auth);
+ * 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.
  *
- * export const query = customQuery(rawQuery, authCtx);
- * export const mutation = customMutation(rawMutation, authCtx);
- * ```
+ * @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>;
+/**
+ * Infer the typed `AuthApiRefs` for the client SDK from a `createAuth` call.
  *
- * Then in any function file:
+ * Use this as the generic parameter for `client()` on the frontend:
  *
  * ```ts
- * // convex/messages.ts
- * import { query, mutation } from "./functions";
+ * // convex/auth.ts
+ * export const auth = createAuth(components.auth, { providers: [...] });
  *
- * export const list = query({
- *   args: {},
- *   handler: async (ctx) => {
- *     // ctx.auth.userId and ctx.auth.user are already resolved
- *     return ctx.db.query("messages").collect();
- *   },
- * });
+ * // Frontend
+ * import type { auth } from "../convex/auth";
+ * import type { InferClientApi } from "@robelest/convex-auth/server";
+ * const c = client<InferClientApi<typeof auth>>({ convex, api: api.auth });
  * ```
  *
- * ### Optional auth (public routes)
+ * @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>> = {
+  /** 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;
+};
+/**
+ * Create a context enrichment for `customQuery` / `customMutation` — optional auth.
  *
- * ```ts
- * export const publicQuery = customQuery(rawQuery, AuthCtx(auth, { optional: true }));
- * // ctx.auth.userId is null when unauthenticated
- * ```
+ * When `optional: true` is set, unauthenticated requests are allowed.
+ * The enriched `ctx.auth` will have `userId: null` and `user: null`
+ * for unauthenticated callers.
  *
- * ### Multi-tenant with group resolution
+ * @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, {
- *   resolve: async (ctx, user) => {
- *     const groupId = user?.extend?.lastActiveGroup;
- *     const membership = await auth.user.group.get(ctx, {
- *       userId: user._id,
- *       groupId,
- *     });
- *     return { groupId, role: membership?.role ?? "member" };
- *   },
+ *   optional: true,
+ *   resolve: async (_ctx, user) => ({ plan: user?.extend?.plan ?? null }),
  * });
- * // ctx.auth.groupId and ctx.auth.role available in handlers
  * ```
  *
- * @param auth - The `Auth` class instance from your `convex/auth.ts`.
- * @param config - Optional configuration for optional auth and group resolution.
- * @returns A `{ args, input }` customization object compatible with
- *          `customQuery` / `customMutation` from `convex-helpers`.
+ * @see {@link createAuth}
  */
-/**
- * Overload: optional auth — `userId` and `user` may be `null`.
- */
-declare function AuthCtx<TResolve extends Record<string, unknown> = Record<string, never>>(auth: Auth, config: AuthCtxConfig<TResolve> & {
+declare function AuthCtx<TResolve extends Record<string, unknown> = Record<string, never>>(auth: AuthLike, config: AuthCtxConfig<TResolve> & {
   optional: true;
 }): {
   args: {};
@@ -408,7 +345,7 @@ declare function AuthCtx<TResolve extends Record<string, unknown> = Record<strin
     ctx: {
       auth: {
         getUserIdentity: () => Promise<UserIdentity | null>;
-        userId: GenericId<"user"> | null;
+        userId: GenericId<"User"> | null;
         user: UserDoc | null;
       } & TResolve;
     };
@@ -416,15 +353,35 @@ declare function AuthCtx<TResolve extends Record<string, unknown> = Record<strin
   }>;
 };
 /**
- * Overload: required auth (default) — `userId` and `user` are never `null`.
+ * 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: Auth, config?: AuthCtxConfig<TResolve>): {
+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: {
         getUserIdentity: () => Promise<UserIdentity | null>;
-        userId: GenericId<"user">;
+        userId: GenericId<"User">;
         user: UserDoc;
       } & TResolve;
     };
@@ -432,19 +389,27 @@ declare function AuthCtx<TResolve extends Record<string, unknown> = Record<strin
   }>;
 };
 /**
- * Extract the `ctx.auth` shape from an {@link AuthCtx} result.
+ * 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.
  *
- * Follows the same pattern as `Infer<typeof validator>` in Convex
- * and `z.infer<typeof schema>` in Zod.
+ * @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) => ({ groupId: "abc", role: "admin" }),
+ *   resolve: async (ctx, user) => ({ orgId: user.orgId }),
  * });
- * type MyAuth = InferAuth<typeof authCtx>;
- * // { getUserIdentity, userId, user, groupId: string, role: string }
+ * 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<{
@@ -454,5 +419,5 @@ type InferAuth<T extends {
   }>;
 }> = Awaited<ReturnType<T["input"]>>["ctx"]["auth"];
 //#endregion
-export { Auth, AuthClassConfig, AuthCtx, AuthCtxConfig, InferAuth, UserDoc };
+export { AuthApi, AuthApiBase, AuthConfig, AuthCtx, AuthCtxConfig, AuthResolvedContext, ConvexAuthResult, InferAuth, InferClientApi, UserDoc, createAuth };
 //# sourceMappingURL=auth.d.ts.map