@robelest/convex-auth 0.0.4-preview.13 → 0.0.4-preview.16

package/src/server/auth.ts

@@ -8,12 +8,16 @@ 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 "./implementation";
 import type { Doc } from "./types";
 import type {
+  AuthAuthorizationConfig,
+  AuthGrant,
   AuthProviderConfig,
+  AuthRoleDefinition,
+  AuthRoleId,
   ConvexAuthConfig,
   HasDeviceProvider,
   HasPasskeyProvider,
@@ -31,8 +35,105 @@ import type {
  */
 export type AuthConfig = Omit<ConvexAuthConfig, "component">;
 
+type MemberApiWithAuthorization<
+  TAuthorization extends AuthAuthorizationConfig | undefined,
+> = Omit<
+  ReturnType<typeof AuthFactory>["auth"]["member"],
+  "create" | "list" | "update" | "inherit" | "require"
+> & {
+  create: (
+    ctx: Parameters<
+      ReturnType<typeof AuthFactory>["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 AuthFactory>["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 AuthFactory>["auth"]["member"]["list"]>;
+  update: (
+    ctx: Parameters<
+      ReturnType<typeof AuthFactory>["auth"]["member"]["update"]
+    >[0],
+    memberId: string,
+    data: Record<string, unknown> & { roleIds?: AuthRoleId<TAuthorization>[] },
+  ) => Promise<{ ok: true; memberId: string }>;
+  inherit: (
+    ctx: Parameters<
+      ReturnType<typeof AuthFactory>["auth"]["member"]["inherit"]
+    >[0],
+    opts: {
+      userId: string;
+      groupId: string;
+      roleIds?: AuthRoleId<TAuthorization>[];
+      grants?: AuthGrant<TAuthorization>[];
+      maxDepth?: number;
+    },
+  ) => ReturnType<ReturnType<typeof AuthFactory>["auth"]["member"]["inherit"]>;
+  require: (
+    ctx: Parameters<
+      ReturnType<typeof AuthFactory>["auth"]["member"]["require"]
+    >[0],
+    opts: {
+      userId: string;
+      groupId: string;
+      roleIds?: AuthRoleId<TAuthorization>[];
+      grants?: AuthGrant<TAuthorization>[];
+      maxDepth?: number;
+    },
+  ) => ReturnType<ReturnType<typeof AuthFactory>["auth"]["member"]["require"]>;
+};
+
+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"]>;
+  require: (
+    ctx: Parameters<
+      ReturnType<typeof AuthFactory>["auth"]["access"]["require"]
+    >[0],
+    opts: {
+      userId: string;
+      groupId: string;
+      grants: AuthGrant<TAuthorization>[];
+      maxDepth?: number;
+    },
+  ) => ReturnType<ReturnType<typeof AuthFactory>["auth"]["access"]["require"]>;
+};
+
 /** The base auth API surface, without conditional namespaces. */
-export type AuthApiBase = {
+export type AuthApiBase<
+  TAuthorization extends AuthAuthorizationConfig | undefined = undefined,
+> = {
   signIn: ReturnType<typeof AuthFactory>["signIn"];
   signOut: ReturnType<typeof AuthFactory>["signOut"];
   store: ReturnType<typeof AuthFactory>["store"];
@@ -41,24 +142,115 @@ export type AuthApiBase = {
   provider: ReturnType<typeof AuthFactory>["auth"]["provider"];
   account: ReturnType<typeof AuthFactory>["auth"]["account"];
   group: ReturnType<typeof AuthFactory>["auth"]["group"];
-  member: ReturnType<typeof AuthFactory>["auth"]["member"];
+  member: MemberApiWithAuthorization<TAuthorization>;
+  access: AccessApiWithAuthorization<TAuthorization>;
   invite: ReturnType<typeof AuthFactory>["auth"]["invite"];
   key: ReturnType<typeof AuthFactory>["auth"]["key"];
   http: ReturnType<typeof AuthFactory>["auth"]["http"];
 };
 
-/** Auth API with SSO namespace — present only when `new SSO()` is in providers. */
-export type AuthApi = AuthApiBase & {
-  sso: ReturnType<typeof AuthFactory>["auth"]["sso"];
+type InternalSsoApi = ReturnType<typeof AuthFactory>["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;
+        }>;
+      }>;
+      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;
+          };
+        }>;
+        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 }>;
+        }>;
+      };
+    };
+  };
+  oidc: Omit<InternalSsoApi["oidc"], "signIn">;
+  saml: Omit<InternalSsoApi["saml"], "metadata">;
+  policy: InternalSsoApi["policy"];
+  audit: {
+    list: InternalSsoApi["audit"]["list"];
+  };
+  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">;
+};
+
+/** Auth API with enterprise namespaces — present only when `new SSO()` is in providers. */
+export type AuthApi<
+  TAuthorization extends AuthAuthorizationConfig | undefined = undefined,
+> = AuthApiBase<TAuthorization> & {
+  sso: PublicSsoApi;
+  scim: PublicScimApi;
 };
 
 /**
  * The return type of `createAuth`. Conditional namespaces:
- * - `auth.sso` — only when `new SSO()` is in providers
+ * - `auth.sso` and `auth.scim` — only when `new SSO()` is in providers
  * - `auth.clientApi` — typed API refs for the client SDK with capabilities
  */
-export type ConvexAuthResult<P extends AuthProviderConfig[]> =
-  HasSSO<P> extends true ? AuthApi : AuthApiBase;
+export 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.
@@ -72,7 +264,7 @@ export type ConvexAuthResult<P extends AuthProviderConfig[]> =
  * // Frontend
  * import type { auth } from "../convex/auth";
  * import type { InferClientApi } from "@robelest/convex-auth/component";
- * const c = client<InferClientApi<typeof auth>>({ convex, api: { ... } });
+ * const c = client<InferClientApi<typeof auth>>({ convex, api: api.auth });
  * ```
  */
 export type InferClientApi<T> =
@@ -94,19 +286,182 @@ export type AuthLike = Pick<AuthApiBase, "user">;
 /**
  * Create an auth API object.
  *
- * When `new SSO()` is included in providers, `auth.sso` is available
- * on the returned object. Without it, `auth.sso` is absent and
- * accessing it is a TypeScript compile error.
+ * 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.
  */
-export function createAuth<P extends AuthProviderConfig[]>(
+export function createAuth<
+  P extends AuthProviderConfig[],
+  TAuthorization extends AuthAuthorizationConfig | undefined = undefined,
+>(
   component: ConvexAuthConfig["component"],
-  config: Omit<AuthConfig, "providers"> & { providers: P },
-): ConvexAuthResult<P> {
+  config: Omit<AuthConfig, "providers" | "authorization"> & {
+    providers: P;
+    authorization?: TAuthorization;
+  },
+): ConvexAuthResult<P, TAuthorization> {
   const authResult = AuthFactory({
     ...config,
     component,
     providers: [...config.providers],
   });
+  const {
+    domain: domainApi,
+    scim: scimApi,
+    connection: connectionApi,
+    audit: auditApi,
+    webhook: webhookApi,
+    oidc: oidcApi,
+    saml: samlApi,
+    ...restSso
+  } = authResult.auth.sso as InternalSsoApi;
+
+  type SetEnterpriseDomains = PublicSsoAdminApi["connection"]["domain"]["set"];
+  type EnterpriseDomainInput = Array<{
+    domain: string;
+    isPrimary?: boolean;
+  }>;
+  const setEnterpriseDomains: PublicSsoAdminApi["connection"]["domain"]["set"] =
+    async (
+      ctx: Parameters<SetEnterpriseDomains>[0],
+      enterpriseId: Parameters<SetEnterpriseDomains>[1],
+      domains: EnterpriseDomainInput,
+    ) => {
+      const enterprise = await connectionApi.get(ctx, enterpriseId);
+      if (enterprise === null) {
+        throw new AuthError(
+          "INVALID_PARAMETERS",
+          "Enterprise not found.",
+        ).toConvexError();
+      }
+
+      const normalized = domains.map((entry: (typeof domains)[number]) => ({
+        ...entry,
+        domain: entry.domain.trim().toLowerCase(),
+      }));
+      const deduped = new Map<string, (typeof normalized)[number]>();
+      for (const entry of normalized) {
+        if (entry.domain.length === 0) {
+          throw new AuthError(
+            "INVALID_PARAMETERS",
+            "Domain must not be empty.",
+          ).toConvexError();
+        }
+        if (deduped.has(entry.domain)) {
+          throw new AuthError(
+            "INVALID_PARAMETERS",
+            `Duplicate domain: ${entry.domain}`,
+          ).toConvexError();
+        }
+        deduped.set(entry.domain, entry);
+      }
+
+      const nextDomains = [...deduped.values()];
+      const primaryCount = nextDomains.filter(
+        (entry) => entry.isPrimary,
+      ).length;
+      if (primaryCount > 1) {
+        throw new AuthError(
+          "INVALID_PARAMETERS",
+          "Only one primary domain may be set.",
+        ).toConvexError();
+      }
+      if (nextDomains.length > 0 && primaryCount === 0) {
+        nextDomains[0] = { ...nextDomains[0], isPrimary: true };
+      }
+
+      const currentDomains = await domainApi.list(ctx, enterpriseId);
+      const currentByDomain = new Map<string, (typeof currentDomains)[number]>(
+        currentDomains.map((entry: (typeof currentDomains)[number]) => [
+          entry.domain.toLowerCase(),
+          entry,
+        ]),
+      );
+
+      for (const existing of currentDomains) {
+        if (!deduped.has(existing.domain.toLowerCase())) {
+          await domainApi.remove(ctx, existing._id);
+        }
+      }
+
+      for (const nextDomain of nextDomains) {
+        const current = currentByDomain.get(nextDomain.domain);
+        if (current && current.isPrimary === Boolean(nextDomain.isPrimary)) {
+          continue;
+        }
+        if (current) {
+          await domainApi.remove(ctx, current._id);
+        }
+        const domainId = await domainApi.add(ctx, {
+          enterpriseId: enterprise._id,
+          groupId: enterprise.groupId,
+          domain: nextDomain.domain,
+          isPrimary: nextDomain.isPrimary,
+        });
+        if (current?.verifiedAt !== undefined) {
+          await (ctx as any).runMutation(
+            component.public.enterpriseDomainVerify,
+            {
+              domainId,
+              verifiedAt: current.verifiedAt,
+            },
+          );
+        }
+      }
+
+      const updatedDomains = await domainApi.list(ctx, enterpriseId);
+      return {
+        ok: true as const,
+        enterpriseId,
+        domains: updatedDomains.map(
+          (domain: (typeof updatedDomains)[number]) => ({
+            domainId: domain._id,
+            domain: domain.domain,
+            isPrimary: domain.isPrimary,
+            verified: domain.verifiedAt !== undefined,
+            verifiedAt: domain.verifiedAt ?? null,
+          }),
+        ),
+      };
+    };
+
+  const publicSso: PublicSsoApi = {
+    admin: {
+      ...restSso,
+      oidc: {
+        ...oidcApi,
+      },
+      saml: {
+        ...samlApi,
+      },
+      connection: {
+        ...connectionApi,
+        domain: {
+          list: domainApi.list,
+          validate: domainApi.validate,
+          set: setEnterpriseDomains,
+          verification: {
+            request: domainApi.verification.request,
+            confirm: domainApi.verification.confirm,
+          },
+        },
+      },
+      policy: restSso.policy,
+      audit: {
+        list: auditApi.list,
+      },
+      webhook: {
+        endpoint: webhookApi.endpoint,
+        delivery: {
+          list: webhookApi.delivery.list,
+        },
+      },
+    },
+    client: {
+      signIn: oidcApi.signIn,
+      metadata: samlApi.metadata,
+    },
+  };
 
   return {
     signIn: authResult.signIn,
@@ -118,11 +473,51 @@ export function createAuth<P extends AuthProviderConfig[]>(
     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: authResult.auth.sso,
+    sso: publicSso,
+    scim: {
+      admin: {
+        configure: scimApi.configure,
+        get: scimApi.get,
+        validate: scimApi.validate,
+      },
+    },
     http: authResult.auth.http,
-  } as ConvexAuthResult<P>;
+  } as unknown as ConvexAuthResult<P, TAuthorization>;
+}
+
+export function defineRoles<
+  const TRoles extends Record<
+    string,
+    { label?: string; grants: readonly string[] }
+  >,
+>(
+  roles: TRoles,
+): {
+  [K in keyof TRoles]: {
+    id: K & string;
+    label?: TRoles[K]["label"];
+    grants: Array<TRoles[K]["grants"][number] & string>;
+  };
+} {
+  return Object.fromEntries(
+    Object.entries(roles).map(([id, role]) => [
+      id,
+      {
+        id,
+        ...(role.label ? { label: role.label } : {}),
+        grants: [...role.grants],
+      },
+    ]),
+  ) as {
+    [K in keyof TRoles]: {
+      id: K & string;
+      label?: TRoles[K]["label"];
+      grants: Array<TRoles[K]["grants"][number] & string>;
+    };
+  };
 }
 
 // ============================================================================

package/src/server/cookies.ts

@@ -1,5 +1,6 @@
 import { isLocalHost } from "./utils";
 
+/** @internal */
 export const SHARED_COOKIE_OPTIONS = {
   httpOnly: true,
   sameSite: "none" as const,
@@ -9,6 +10,7 @@ export const SHARED_COOKIE_OPTIONS = {
 };
 
 const REDIRECT_MAX_AGE = 60 * 15; // 15 minutes in seconds
+/** @internal */
 export function redirectToParamCookie(providerId: string, redirectTo: string) {
   return {
     name: redirectToParamCookieName(providerId),
@@ -17,6 +19,7 @@ export function redirectToParamCookie(providerId: string, redirectTo: string) {
   };
 }
 
+/** @internal */
 export function useRedirectToParam(
   providerId: string,
   cookies: Record<string, string | undefined>,

package/src/server/db.ts

@@ -56,10 +56,13 @@ type AuthComponentApiLike = {
   };
 };
 
+/** @internal */
 export type AuthDbConfig = { component: AuthComponentApiLike };
 
+/** @internal */
 export type AuthDb = ReturnType<typeof authDb>;
 
+/** @internal */
 export function authDb(ctx: CtxLike, config: AuthDbConfig) {
   const component = config.component;
   return {

package/src/server/device.ts

@@ -13,6 +13,7 @@
 import { Fx } from "@robelest/fx";
 
 import { AuthError } from "./fx";
+import { userIdFromIdentitySubject } from "./identity";
 import { callSignIn } from "./mutations/index";
 import { DeviceProviderConfig, GenericActionCtxWithAuthConfig } from "./types";
 import {
@@ -63,6 +64,7 @@ type DeviceResult =
     }
   | { kind: "signedIn"; signedIn: SessionInfo | null };
 
+/** @internal */
 export const handleDevice = (
   ctx: EnrichedActionCtx,
   provider: DeviceProviderConfig,
@@ -187,7 +189,7 @@ export const handleDevice = (
         );
       }
 
-      const userId = identity.subject.split("|")[0]!;
+      const userId = userIdFromIdentitySubject(identity.subject);
       const doc = await queryDeviceByUserCode(ctx, params.userCode);
       if (doc === null) {
         throw new AuthError("DEVICE_INVALID_USER_CODE");