@robelest/convex-auth 0.0.2-preview.1 → 0.0.2

package/src/server/implementation/index.ts

@@ -1,19 +1,17 @@
 import { OAuth2Config, OAuthConfig } from "@auth/core/providers";
 import {
   Auth,
-  DocumentByName,
   GenericActionCtx,
   GenericDataModel,
   HttpRouter,
-  WithoutSystemFields,
   actionGeneric,
   httpActionGeneric,
   internalMutationGeneric,
 } from "convex/server";
-import { ConvexError, GenericId, Value, v } from "convex/values";
+import { ConvexError, GenericId, v } from "convex/values";
 import { parse as parseCookies, serialize as serializeCookie } from "cookie";
 import { redirectToParamCookie, useRedirectToParam } from "../cookies.js";
-import { FunctionReferenceFromExport, GenericDoc } from "../convex_types.js";
+import { FunctionReferenceFromExport } from "../convex_types.js";
 import {
   configDefaults,
   listAvailableProviders,
@@ -22,7 +20,6 @@ import {
 import {
   AuthProviderConfig,
   ConvexAuthConfig,
-  GenericActionCtxWithAuthConfig,
 } from "../types.js";
 import { requireEnv } from "../utils.js";
 import { ActionCtx, MutationCtx, Tokens } from "./types.js";
@@ -53,7 +50,6 @@ import {
   oAuthConfigToInternalProvider,
 } from "../oauth/convexAuth.js";
 import { handleOAuth } from "../oauth/callback.js";
-export { getAuthSessionId } from "./sessions.js";
 
 /**
  * The type of the signIn Convex Action returned from the auth() helper.
@@ -118,15 +114,25 @@ export function Auth(config_: ConvexAuthConfig) {
     }
     return provider;
   };
-  const enrichCtx = <DataModel extends GenericDataModel>(
-    ctx: GenericActionCtx<DataModel>,
-  ) => ({ ...ctx, auth: { ...ctx.auth, config } });
   type ComponentCtx = Pick<
     GenericActionCtx<GenericDataModel>,
     "runQuery" | "runMutation"
   >;
   type ComponentReadCtx = Pick<GenericActionCtx<GenericDataModel>, "runQuery">;
   type ComponentAuthReadCtx = ComponentReadCtx & { auth: Auth };
+  type AccountCredentials = { id: string; secret?: string };
+  type CreateAccountArgs = {
+    provider: string;
+    account: AccountCredentials;
+    profile: Record<string, unknown>;
+    shouldLinkViaEmail?: boolean;
+    shouldLinkViaPhone?: boolean;
+  };
+  type RetrieveAccountArgs = { provider: string; account: AccountCredentials };
+  type UpdateAccountCredentialsArgs = {
+    provider: string;
+    account: { id: string; secret: string };
+  };
 
   const auth = {
     user: {
@@ -198,6 +204,97 @@ export function Auth(config_: ConvexAuthConfig) {
         },
       },
     },
+    session: {
+      /**
+       * Get the current session ID from the auth context, or `null` if
+       * not signed in.
+       */
+      current: async (ctx: { auth: Auth }) => {
+        const identity = await ctx.auth.getUserIdentity();
+        if (identity === null) {
+          return null;
+        }
+        const [, sessionId] = identity.subject.split(TOKEN_SUB_CLAIM_DIVIDER);
+        return sessionId as GenericId<"session">;
+      },
+      /**
+       * Invalidate sessions for a user, optionally preserving specific sessions.
+       */
+      invalidate: async <DataModel extends GenericDataModel>(
+        ctx: GenericActionCtx<DataModel>,
+        args: {
+          userId: GenericId<"user">;
+          except?: GenericId<"session">[];
+        },
+      ): Promise<void> => {
+        const actionCtx = ctx as unknown as ActionCtx;
+        return await callInvalidateSessions(actionCtx, args);
+      },
+    },
+    account: {
+      /**
+       * Create an account and user for a credentials provider.
+       */
+      create: async <DataModel extends GenericDataModel>(
+        ctx: GenericActionCtx<DataModel>,
+        args: CreateAccountArgs,
+      ) => {
+        const actionCtx = ctx as unknown as ActionCtx;
+        return await callCreateAccountFromCredentials(actionCtx, args as any);
+      },
+      /**
+       * Retrieve an account and user for a credentials provider.
+       */
+      get: async <DataModel extends GenericDataModel>(
+        ctx: GenericActionCtx<DataModel>,
+        args: RetrieveAccountArgs,
+      ) => {
+        const actionCtx = ctx as unknown as ActionCtx;
+        const result = await callRetreiveAccountWithCredentials(actionCtx, args);
+        if (typeof result === "string") {
+          throw new Error(result);
+        }
+        return result;
+      },
+      /**
+       * Update credentials for an existing account.
+       */
+      updateCredentials: async <DataModel extends GenericDataModel>(
+        ctx: GenericActionCtx<DataModel>,
+        args: UpdateAccountCredentialsArgs,
+      ): Promise<void> => {
+        const actionCtx = ctx as unknown as ActionCtx;
+        return await callModifyAccount(actionCtx, args);
+      },
+    },
+    provider: {
+      /**
+       * Sign in via another provider, typically from a credentials flow.
+       */
+      signIn: async <DataModel extends GenericDataModel>(
+        ctx: GenericActionCtx<DataModel>,
+        provider: AuthProviderConfig,
+        args: {
+          accountId?: GenericId<"account">;
+          params?: Record<string, unknown>;
+        },
+      ) => {
+        const result = await signInImpl(
+          enrichCtx(ctx),
+          materializeProvider(provider),
+          args as any,
+          {
+            generateTokens: false,
+            allowExtraProviders: true,
+          },
+        );
+        return result.kind === "signedIn"
+          ? result.signedIn !== null
+            ? { userId: result.signedIn.userId, sessionId: result.signedIn.sessionId }
+            : null
+          : null;
+      },
+    },
     /**
      * Hierarchical group management. Groups can nest arbitrarily deep
      * via `parentGroupId`. A root group has no parent.
@@ -349,12 +446,15 @@ export function Auth(config_: ConvexAuthConfig) {
        * Create a new invitation.
        *
        * @param data.groupId - Optional group to invite the user into.
-       * @param data.invitedByUserId - The user sending the invitation.
-       * @param data.email - The email address of the invitee.
+       * @param data.invitedByUserId - Optional user sending the invitation
+       *   (omit for CLI-generated invites).
+       * @param data.email - Optional email of the invitee (omit for
+       *   CLI-generated invite links where the email is unknown upfront).
        * @param data.tokenHash - Hashed token for secure acceptance.
        * @param data.role - Optional role to assign on acceptance.
        * @param data.status - Initial status (typically "pending").
-       * @param data.expiresTime - Timestamp when the invite expires.
+       * @param data.expiresTime - Optional expiration timestamp (omit for
+       *   single-use, non-expiring invites).
        * @param data.extend - Optional arbitrary JSON extension data.
        * @throws ConvexError with code `DUPLICATE_INVITE` if a pending invite
        * already exists for this email and scope.
@@ -364,12 +464,12 @@ export function Auth(config_: ConvexAuthConfig) {
         ctx: ComponentCtx,
         data: {
           groupId?: string;
-          invitedByUserId: string;
-          email: string;
+          invitedByUserId?: string;
+          email?: string;
           tokenHash: string;
           role?: string;
           status: "pending" | "accepted" | "revoked" | "expired";
-          expiresTime: number;
+          expiresTime?: number;
           extend?: Record<string, unknown>;
         },
       ): Promise<string> => {
@@ -381,6 +481,12 @@ export function Auth(config_: ConvexAuthConfig) {
       get: async (ctx: ComponentReadCtx, inviteId: string) => {
         return await ctx.runQuery(config.component.public.inviteGet, { inviteId });
       },
+      /**
+       * Retrieve an invite by its token hash. Returns `null` if not found.
+       */
+      getByTokenHash: async (ctx: ComponentReadCtx, tokenHash: string) => {
+        return await ctx.runQuery(config.component.public.inviteGetByTokenHash, { tokenHash });
+      },
       /**
        * List invites, optionally filtered by group and/or status.
        */
@@ -427,8 +533,11 @@ export function Auth(config_: ConvexAuthConfig) {
        * });
        * ```
        */
-      accept: async (ctx: ComponentCtx, inviteId: string) => {
-        await ctx.runMutation(config.component.public.inviteAccept, { inviteId });
+      accept: async (ctx: ComponentCtx, inviteId: string, acceptedByUserId?: string) => {
+        await ctx.runMutation(config.component.public.inviteAccept, {
+          inviteId,
+          ...(acceptedByUserId ? { acceptedByUserId } : {}),
+        });
       },
        /**
         * Revoke a pending invitation.
@@ -442,6 +551,86 @@ export function Auth(config_: ConvexAuthConfig) {
         await ctx.runMutation(config.component.public.inviteRevoke, { inviteId });
       },
     },
+    /**
+     * Manage passkey credentials for users.
+     *
+     * ```ts
+     * const passkeys = await auth.passkey.list(ctx, { userId });
+     * await auth.passkey.rename(ctx, passkeyId, "MacBook Touch ID");
+     * await auth.passkey.remove(ctx, passkeyId);
+     * ```
+     */
+    passkey: {
+      /**
+       * List all passkeys for a user.
+       *
+       * @param opts.userId - The user whose passkeys to list.
+       * @returns Array of passkey records with credentialId, name, deviceType,
+       * backedUp, createdAt, and lastUsedAt.
+       */
+      list: async (ctx: ComponentReadCtx, opts: { userId: string }) => {
+        return await ctx.runQuery(
+          config.component.public.passkeyListByUserId,
+          opts,
+        );
+      },
+      /**
+       * Rename a passkey (set a user-friendly display name).
+       *
+       * @param passkeyId - The passkey document ID.
+       * @param name - New display name (e.g. "MacBook Touch ID").
+       */
+      rename: async (ctx: ComponentCtx, passkeyId: string, name: string) => {
+        await ctx.runMutation(
+          config.component.public.passkeyUpdateMeta,
+          { passkeyId, data: { name } },
+        );
+      },
+      /**
+       * Delete a passkey credential.
+       *
+       * @param passkeyId - The passkey document ID to remove.
+       */
+      remove: async (ctx: ComponentCtx, passkeyId: string) => {
+        await ctx.runMutation(
+          config.component.public.passkeyDelete,
+          { passkeyId },
+        );
+      },
+    },
+    /**
+     * Manage TOTP two-factor authentication enrollments for users.
+     *
+     * ```ts
+     * const enrollments = await auth.totp.list(ctx, { userId });
+     * await auth.totp.remove(ctx, totpId);
+     * ```
+     */
+    totp: {
+      /**
+       * List all TOTP enrollments for a user.
+       *
+       * @param opts.userId - The user whose enrollments to list.
+       * @returns Array of TOTP enrollment records.
+       */
+      list: async (ctx: ComponentReadCtx, opts: { userId: string }) => {
+        return await ctx.runQuery(
+          config.component.public.totpListByUserId,
+          opts,
+        );
+      },
+      /**
+       * Delete a TOTP enrollment.
+       *
+       * @param totpId - The TOTP document ID to remove.
+       */
+      remove: async (ctx: ComponentCtx, totpId: string) => {
+        await ctx.runMutation(
+          config.component.public.totpDelete,
+          { totpId },
+        );
+      },
+    },
     /**
      * Add HTTP actions for JWT verification and OAuth sign-in.
      *
@@ -655,6 +844,19 @@ export function Auth(config_: ConvexAuthConfig) {
       }
     },
   };
+  const enrichCtx = <DataModel extends GenericDataModel>(
+    ctx: GenericActionCtx<DataModel>,
+  ) => ({
+    ...ctx,
+    auth: {
+      ...ctx.auth,
+      config,
+      account: auth.account,
+      session: auth.session,
+      provider: auth.provider,
+    },
+  });
+
   return {
     /**
      * Helper for configuring HTTP actions.
@@ -681,6 +883,9 @@ export function Auth(config_: ConvexAuthConfig) {
         verifier?: string;
         tokens?: Tokens | null;
         started?: boolean;
+        options?: Record<string, any>;
+        totpRequired?: boolean;
+        totpSetup?: { uri: string; secret: string; totpId: string };
       }> => {
         if (args.calledBy !== undefined) {
           logWithLevel("INFO", `\`auth:signIn\` called by ${args.calledBy}`);
@@ -701,6 +906,12 @@ export function Auth(config_: ConvexAuthConfig) {
             return { tokens: result.signedIn?.tokens ?? null };
           case "started":
             return { started: true };
+          case "passkeyOptions":
+            return { options: result.options, verifier: result.verifier };
+          case "totpRequired":
+            return { totpRequired: true, verifier: result.verifier };
+          case "totpSetup":
+            return { totpSetup: { uri: result.uri, secret: result.secret, totpId: result.totpId }, verifier: result.verifier };
           default: {
             const _typecheck: never = result;
             throw new Error(`Unexpected result from signIn, ${result as any}`);
@@ -732,228 +943,6 @@ export function Auth(config_: ConvexAuthConfig) {
   };
 }
 
-/**
- * Return the currently signed-in user's ID.
- *
- * ```ts filename="convex/myFunctions.tsx"
- * import { mutation } from "./_generated/server";
- * import { getAuthUserId } from "@robelest/convex-auth/component";
- *
- * export const doSomething = mutation({
- *   args: {/* ... *\/},
- *   handler: async (ctx, args) => {
- *     const userId = await getAuthUserId(ctx);
- *     if (userId === null) {
- *       throw new Error("Client is not authenticated!")
- *     }
- *     const user = await ctx.db.get(userId);
- *     // ...
- *   },
- * });
- * ```
- *
- * @param ctx query, mutation or action `ctx`
- * @returns the user ID or `null` if the client isn't authenticated
- */
-export async function getAuthUserId(ctx: { auth: Auth }) {
-  const identity = await ctx.auth.getUserIdentity();
-  if (identity === null) {
-    return null;
-  }
-  const [userId] = identity.subject.split(TOKEN_SUB_CLAIM_DIVIDER);
-  return userId as GenericId<"user">;
-}
-
-/**
- * Use this function from a
- * [`ConvexCredentials`](https://labs.convex.dev/auth/api_reference/providers/ConvexCredentials)
- * provider to create an account and a user with a unique account "id" (OAuth
- * provider ID, email address, phone number, username etc.).
- *
- * @returns user ID if it successfully creates the account
- * or throws an error.
- */
-export async function createAccount<
-  DataModel extends GenericDataModel = GenericDataModel,
->(
-  ctx: GenericActionCtx<DataModel>,
-  args: {
-    /**
-     * The provider ID (like "password"), used to disambiguate accounts.
-     *
-     * It is also used to configure account secret hashing via the provider's
-     * `crypto` option.
-     */
-    provider: string;
-    account: {
-      /**
-       * The unique external ID for the account, for example email address.
-       */
-      id: string;
-      /**
-       * The secret credential to store for this account, if given.
-       */
-      secret?: string;
-    };
-    /**
-     * The profile data to store for the user.
-     * These must fit the `users` table schema.
-     */
-    profile: WithoutSystemFields<DocumentByName<DataModel, "user">>;
-    /**
-     * If `true`, the account will be linked to an existing user
-     * with the same verified email address.
-     * This is only safe if the returned account's email is verified
-     * before the user is allowed to sign in with it.
-     */
-    shouldLinkViaEmail?: boolean;
-    /**
-     * If `true`, the account will be linked to an existing user
-     * with the same verified phone number.
-     * This is only safe if the returned account's phone is verified
-     * before the user is allowed to sign in with it.
-     */
-    shouldLinkViaPhone?: boolean;
-  },
-): Promise<{
-  account: GenericDoc<DataModel, "account">;
-  user: GenericDoc<DataModel, "user">;
-}> {
-  const actionCtx = ctx as unknown as ActionCtx;
-  return (await callCreateAccountFromCredentials(
-    actionCtx,
-    args as any,
-  )) as any;
-}
-
-/**
- * Use this function from a
- * [`ConvexCredentials`](https://labs.convex.dev/auth/api_reference/providers/ConvexCredentials)
- * provider to retrieve a user given the account provider ID and
- * the provider-specific account ID.
- *
- * @returns the retrieved user document, or `null` if there is no account
- * for given account ID or throws if the provided
- * secret does not match.
- */
-export async function retrieveAccount<
-  DataModel extends GenericDataModel = GenericDataModel,
->(
-  ctx: GenericActionCtx<DataModel>,
-  args: {
-    /**
-     * The provider ID (like "password"), used to disambiguate accounts.
-     *
-     * It is also used to configure account secret hashing via the provider's
-     * `crypto` option.
-     */
-    provider: string;
-    account: {
-      /**
-       * The unique external ID for the account, for example email address.
-       */
-      id: string;
-      /**
-       * The secret that should match the stored credential, if given.
-       */
-      secret?: string;
-    };
-  },
-): Promise<{
-  account: GenericDoc<DataModel, "account">;
-  user: GenericDoc<DataModel, "user">;
-}> {
-  const actionCtx = ctx as unknown as ActionCtx;
-  const result = await callRetreiveAccountWithCredentials(actionCtx, args);
-  if (typeof result === "string") {
-    throw new Error(result);
-  }
-  return result as any;
-}
-
-/**
- * Use this function to modify the account credentials
- * from a [`ConvexCredentials`](https://labs.convex.dev/auth/api_reference/providers/ConvexCredentials)
- * provider.
- */
-export async function modifyAccountCredentials<
-  DataModel extends GenericDataModel = GenericDataModel,
->(
-  ctx: GenericActionCtx<DataModel>,
-  args: {
-    /**
-     * The provider ID (like "password"), used to disambiguate accounts.
-     *
-     * It is also used to configure account secret hashing via the `crypto` option.
-     */
-    provider: string;
-    account: {
-      /**
-       * The unique external ID for the account, for example email address.
-       */
-      id: string;
-      /**
-       * The new secret credential to store for this account.
-       */
-      secret: string;
-    };
-  },
-): Promise<void> {
-  const actionCtx = ctx as unknown as ActionCtx;
-  return await callModifyAccount(actionCtx, args);
-}
-
-/**
- * Use this function to invalidate existing sessions.
- */
-export async function invalidateSessions<
-  DataModel extends GenericDataModel = GenericDataModel,
->(
-  ctx: GenericActionCtx<DataModel>,
-  args: {
-    userId: GenericId<"user">;
-    except?: GenericId<"session">[];
-  },
-): Promise<void> {
-  const actionCtx = ctx as unknown as ActionCtx;
-  return await callInvalidateSessions(actionCtx, args);
-}
-
-/**
- * Use this function from a
- * [`ConvexCredentials`](https://labs.convex.dev/auth/api_reference/providers/ConvexCredentials)
- * provider to sign in the user via another provider (usually
- * for email verification on sign up or password reset).
- *
- * Returns the user ID if the sign can proceed,
- * or `null`.
- */
-export async function signInViaProvider<
-  DataModel extends GenericDataModel = GenericDataModel,
->(
-  ctx: GenericActionCtxWithAuthConfig<DataModel>,
-  provider: AuthProviderConfig,
-  args: {
-    accountId?: GenericId<"account">;
-    params?: Record<string, Value | undefined>;
-  },
-) {
-  const result = await signInImpl(
-    ctx,
-    materializeProvider(provider),
-    args as any,
-    {
-    generateTokens: false,
-    allowExtraProviders: true,
-    },
-  );
-  return result.kind === "signedIn"
-    ? result.signedIn !== null
-      ? { userId: result.signedIn.userId, sessionId: result.signedIn.sessionId }
-      : null
-    : null;
-}
-
 function convertErrorsToResponse(
   errorStatusCode: number,
   action: (ctx: GenericActionCtx<any>, request: Request) => Promise<Response>,