@robelest/convex-auth 0.0.4-preview.25 → 0.0.4-preview.28

package/dist/server/auth.d.ts

@@ -1,20 +1,14 @@
-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";
+import { AuthAuthorizationConfig, AuthGrant, AuthProviderConfig, AuthRoleId, ConvexAuthConfig, HasDeviceProvider, HasPasskeyProvider, HasSSO, HasTotpProvider } from "./types.js";
+import { AuthConfig, AuthContext, AuthContextConfig, AuthContextFactory as AuthContextFactory$1, AuthContextResolver as AuthContextResolver$1, InferAuth, OptionalAuthContext, UserDoc } from "./auth-context.js";
+import { Auth } from "./runtime.js";
 
 //#region src/server/auth.d.ts
-/**
- * Config for auth setup. Extends the standard auth config
- * minus `component` (which is passed as the first constructor argument).
- */
-type AuthConfig = Omit<ConvexAuthConfig, "component">;
-/** Canonical user document type exposed by Convex Auth. */
-type UserDoc = Doc<"User">;
-type MemberApiWithAuthorization<TAuthorization extends AuthAuthorizationConfig | undefined> = Omit<ReturnType<typeof Auth$1>["auth"]["member"], "create" | "list" | "update" | "inspect" | "require"> & {
-  create: (ctx: Parameters<ReturnType<typeof Auth$1>["auth"]["member"]["create"]>[0], data: {
+type AuthContextResolver = AuthContextResolver$1;
+type AuthContextFactory = AuthContextFactory$1;
+type MemberApiWithAuthorization<TAuthorization extends AuthAuthorizationConfig | undefined> = Omit<ReturnType<typeof Auth>["auth"]["member"], "create" | "list" | "update" | "inspect" | "require"> & {
+  create: (ctx: Parameters<ReturnType<typeof Auth>["auth"]["member"]["create"]>[0], data: {
     groupId: string;
     userId: string;
     roleIds?: AuthRoleId<TAuthorization>[];
@@ -23,7 +17,7 @@ type MemberApiWithAuthorization<TAuthorization extends AuthAuthorizationConfig |
   }) => Promise<{
     memberId: string;
   }>;
-  list: (ctx: Parameters<ReturnType<typeof Auth$1>["auth"]["member"]["list"]>[0], opts?: {
+  list: (ctx: Parameters<ReturnType<typeof Auth>["auth"]["member"]["list"]>[0], opts?: {
     where?: {
       groupId?: string;
       userId?: string;
@@ -34,26 +28,26 @@ type MemberApiWithAuthorization<TAuthorization extends AuthAuthorizationConfig |
     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> & {
+  }) => ReturnType<ReturnType<typeof Auth>["auth"]["member"]["list"]>;
+  update: (ctx: Parameters<ReturnType<typeof Auth>["auth"]["member"]["update"]>[0], memberId: string, data: Record<string, unknown> & {
     roleIds?: AuthRoleId<TAuthorization>[];
   }) => Promise<{
     memberId: string;
   }>;
-  inspect: (ctx: Parameters<ReturnType<typeof Auth$1>["auth"]["member"]["inspect"]>[0], opts: {
+  inspect: (ctx: Parameters<ReturnType<typeof Auth>["auth"]["member"]["inspect"]>[0], opts: {
     userId: string;
     groupId: string;
     ancestry?: boolean;
     maxDepth?: number;
-  }) => ReturnType<ReturnType<typeof Auth$1>["auth"]["member"]["inspect"]>;
-  require: (ctx: Parameters<ReturnType<typeof Auth$1>["auth"]["member"]["require"]>[0], opts: {
+  }) => ReturnType<ReturnType<typeof Auth>["auth"]["member"]["inspect"]>;
+  require: (ctx: Parameters<ReturnType<typeof Auth>["auth"]["member"]["require"]>[0], opts: {
     userId: string;
     groupId: string;
     ancestry?: boolean;
     roleIds?: AuthRoleId<TAuthorization>[];
     grants?: AuthGrant<TAuthorization>[];
     maxDepth?: number;
-  }) => ReturnType<ReturnType<typeof Auth$1>["auth"]["member"]["require"]>;
+  }) => ReturnType<ReturnType<typeof Auth>["auth"]["member"]["require"]>;
 };
 /**
  * The base auth API surface returned by {@link createAuth}.
@@ -61,28 +55,28 @@ type MemberApiWithAuthorization<TAuthorization extends AuthAuthorizationConfig |
  * 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
+ * Group SSO helpers under `group.sso` 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.
+ * standard auth surface and should not assume group connection 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"];
-  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"];
+  signIn: ReturnType<typeof Auth>["signIn"];
+  signOut: ReturnType<typeof Auth>["signOut"];
+  store: ReturnType<typeof Auth>["store"];
+  user: ReturnType<typeof Auth>["auth"]["user"];
+  session: ReturnType<typeof Auth>["auth"]["session"];
+  provider: ReturnType<typeof Auth>["auth"]["provider"];
+  account: ReturnType<typeof Auth>["auth"]["account"];
+  group: ReturnType<typeof Auth>["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"];
+  invite: ReturnType<typeof Auth>["auth"]["invite"];
+  key: ReturnType<typeof Auth>["auth"]["key"];
+  http: ReturnType<typeof Auth>["auth"]["http"];
   /**
    * Resolve the current request's auth context. Framework-agnostic — use
    * this in fluent-convex middleware, custom wrappers, or anywhere you
@@ -104,19 +98,19 @@ type AuthApiBase<TAuthorization extends AuthAuthorizationConfig | undefined = un
    * ```
    *
    * @example Direct usage in a handler
-    * ```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;
-    * }
-    * ```
-    */
+   * ```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` /
@@ -158,101 +152,33 @@ type AuthApiBase<TAuthorization extends AuthAuthorizationConfig | undefined = un
    */
   ctx: AuthContextFactory;
 };
-/**
- * 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.
- * - `grants` is `[]` when no active group or no membership is resolved.
- *
- * @example
- * ```ts
- * import type { AuthContext } from "@robelest/convex-auth/server";
- *
- * const mockAuth: AuthContext = {
- *   userId: "user123" as Id<"User">,
- *   user: { _id: "user123", email: "test@example.com" },
- *   groupId: "group456",
- *   role: "admin",
- *   grants: ["read", "write"],
- * };
- * ```
- */
-type AuthContext = {
-  /** The authenticated user's document ID. */userId: GenericId<"User">; /** The authenticated user's full document. */
-  user: UserDoc; /** The user's active group ID, or `null` if none set. */
-  groupId: string | null; /** The user's primary role in the active group, or `null`. */
-  role: string | null; /** Resolved grant strings from the user's role definitions. */
-  grants: string[];
-};
-/**
- * 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 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 InternalSsoApi = ReturnType<typeof Auth>["auth"]["sso"];
+type PublicGroupSsoApi = {
+  signIn: (ctx: Parameters<InternalSsoApi["connection"]["create"]>[0], data: {
+    connectionId?: string;
+    email?: string;
+    domain?: string;
+    redirectTo?: string;
+    loginHint?: string;
+  }) => Promise<{
+    connectionId: string;
+    protocol: "oidc" | "saml";
+    providerId: string;
+    signInPath: string;
+    callbackPath: string;
+    redirectTo?: string;
   }>;
-};
-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$1>["auth"]["sso"];
-type PublicSsoAdminApi = {
+  metadata: InternalSsoApi["saml"]["metadata"];
   connection: InternalSsoApi["connection"] & {
     domain: {
       list: InternalSsoApi["domain"]["list"];
       validate: InternalSsoApi["domain"]["validate"];
-      set: (ctx: Parameters<InternalSsoApi["connection"]["create"]>[0], enterpriseId: string, domains: Array<{
+      status: InternalSsoApi["domain"]["status"];
+      set: (ctx: Parameters<InternalSsoApi["connection"]["create"]>[0], connectionId: string, domains: Array<{
         domain: string;
         isPrimary?: boolean;
       }>) => Promise<{
-        enterpriseId: string;
+        connectionId: string;
         domains: Array<{
           domainId: string;
           domain: string;
@@ -263,10 +189,10 @@ type PublicSsoAdminApi = {
       }>;
       verification: {
         request: (ctx: Parameters<InternalSsoApi["connection"]["create"]>[0], args: {
-          enterpriseId: string;
+          connectionId: string;
           domain: string;
         }) => Promise<{
-          enterpriseId: string;
+          connectionId: string;
           domain: string;
           requestedAt: number;
           expiresAt: number;
@@ -277,10 +203,10 @@ type PublicSsoAdminApi = {
           };
         }>;
         confirm: (ctx: Parameters<InternalSsoApi["connection"]["create"]>[0], args: {
-          enterpriseId: string;
+          connectionId: string;
           domain: string;
         }) => Promise<{
-          enterpriseId: string;
+          connectionId: string;
           domain: string;
           verifiedAt?: number;
           checks: Array<{
@@ -293,7 +219,7 @@ type PublicSsoAdminApi = {
     };
   };
   oidc: Omit<InternalSsoApi["oidc"], "signIn">;
-  saml: Omit<InternalSsoApi["saml"], "metadata">;
+  saml: InternalSsoApi["saml"];
   policy: InternalSsoApi["policy"];
   audit: {
     list: InternalSsoApi["audit"]["list"];
@@ -304,27 +230,17 @@ type PublicSsoAdminApi = {
       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">;
+  scim: Omit<InternalSsoApi["scim"], "getConfigByToken" | "identity">;
 };
 /**
- * Extended auth API that includes enterprise SSO and SCIM namespaces.
+ * Extended auth API that includes group 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
+ * This type is the union of {@link AuthApiBase} plus `group.sso`
+ * (SSO connection management, OIDC/SAML, SCIM, domain verification,
+ * policies, audit, and webhooks). It is returned by
+ * {@link createAuth} only when `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
+ * Attempting to access `auth.group.sso` without an SSO provider
  * produces a compile-time error because the return type narrows back to
  * {@link AuthApiBase}.
  *
@@ -332,18 +248,19 @@ type PublicScimApi = {
  *   {@link AuthApiBase} for typed role IDs and grant strings.
  */
 type AuthApi<TAuthorization extends AuthAuthorizationConfig | undefined = undefined> = AuthApiBase<TAuthorization> & {
-  sso: PublicSsoApi;
-  scim: PublicScimApi;
+  group: AuthApiBase<TAuthorization>["group"] & {
+    sso: PublicGroupSsoApi;
+  };
 };
 /**
  * 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
+ * Resolves to {@link AuthApi} (with `group.sso` helpers) when
+ * `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
+ * group connection-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.
+ * `auth.group.sso` without it.
  * This lets application code keep a single `createAuth()` call while still
  * getting provider-aware typing on the resulting API object.
  *
@@ -369,98 +286,36 @@ type ConvexAuthResult<P extends AuthProviderConfig[], TAuthorization extends Aut
  * @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>;
-/**
- * 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 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 createAuth().ctx}.
-   *
-   * Return `undefined` to fall back to the built-in resolver,
-   * `null` for an explicit unauthenticated state, or an
-   * {@link AuthContext} object to provide a pre-resolved auth state.
-   * This is useful for tests, proxy auth, impersonation flows, or any
-   * environment that needs to inject auth without depending on the standard
-   * Convex auth tables.
-   *
-   * @param ctx - The Convex function context.
-   * @param fallback - The built-in auth resolver used by {@link createAuth().ctx}.
-   * @returns Resolved auth state, `null`, or `undefined` to use the fallback.
-   *
-   * @example
-   * ```ts
-   * const authCtx = auth.ctx({
-   *   authResolve: async (ctx, fallback) => {
-   *     const injected = getInjectedAuth(ctx);
-   *     return injected ?? (await fallback());
-   *   },
-   * });
-   * ```
-   */
-  authResolve?: (ctx: any, fallback: () => Promise<AuthContext | null>) => Promise<AuthContext | null | undefined> | AuthContext | null | undefined;
-};
 /**
- * Extract the resolved `auth` context type from an `auth.ctx()` customization.
+ * Create an auth API object.
  *
- * Use this to type function parameters or variables that receive the
- * 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.
+ * When `sso()` is included in providers, `auth.group.sso` is available
+ * on the returned object. Without it, that namespace is absent and
+ * accessing it is a TypeScript compile error.
  *
- * @typeParam T - An `auth.ctx()` return value (must have an `input` method
- *   that returns `{ ctx: { auth: ... } }`).
+ * @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 `group.sso`) or {@link AuthApiBase}, depending on whether
+ *   an SSO provider is present.
  *
  * @example
  * ```ts
- * const authCtx = auth.ctx({
- *   resolve: async (ctx, user) => ({ orgId: user.orgId }),
+ * export const auth = createAuth(components.auth, {
+ *   providers: [password(), google()],
+ *   authorization: { roles },
  * });
- * type Auth = InferAuth<typeof authCtx>;
- * // Auth = { userId: Id<"User">; user: UserDoc; getUserIdentity: ...; orgId: string }
  * ```
  *
- * @see {@link createAuth}
+ * @see {@link AuthContextConfig}
  */
-type InferAuth<T extends {
-  input: (...args: any[]) => Promise<{
-    ctx: {
-      auth: any;
-    };
-  }>;
-}> = Awaited<ReturnType<T["input"]>>["ctx"]["auth"];
+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>;
 //#endregion
-export { AuthApi, AuthApiBase, AuthConfig, AuthContext, AuthContextConfig, ConvexAuthResult, InferAuth, InferClientApi, OptionalAuthContext, UserDoc, createAuth };
+export { AuthApi, AuthApiBase, ConvexAuthResult, InferClientApi, createAuth };
 //# sourceMappingURL=auth.d.ts.map