@robelest/convex-auth 0.0.1

package/src/providers/ConvexCredentials.ts

@@ -0,0 +1,108 @@
+/**
+ * Configure {@link ConvexCredentials} provider given a {@link ConvexCredentialsUserConfig}.
+ *
+ * This is for a very custom authentication implementation, often you can
+ * use the [`Password`](https://labs.convex.dev/auth/api_reference/providers/Password) provider instead.
+ *
+ * ```ts
+ * import ConvexCredentials from "@robelest/convex-auth/providers/ConvexCredentials";
+ * import { convexAuth } from "@robelest/convex-auth/component";
+ *
+ * export const { auth, signIn, signOut, store } = convexAuth({
+ *   providers: [
+ *     ConvexCredentials({
+ *       authorize: async (credentials, ctx) => {
+ *         // Your custom logic here...
+ *       },
+ *     }),
+ *   ],
+ * });
+ * ```
+ *
+ * @module
+ */
+
+import {
+  AuthProviderConfig,
+  ConvexCredentialsConfig,
+  GenericActionCtxWithAuthConfig,
+} from "@robelest/convex-auth/component";
+import { GenericDataModel } from "convex/server";
+import { GenericId, Value } from "convex/values";
+
+/**
+ * The available options to a {@link ConvexCredentials} provider for Convex Auth.
+ */
+export interface ConvexCredentialsUserConfig<
+  DataModel extends GenericDataModel = GenericDataModel,
+> {
+  /**
+   * Uniquely identifies the provider, allowing to use
+   * multiple different {@link ConvexCredentials} providers.
+   */
+  id?: string;
+  /**
+   * Gives full control over how you handle the credentials received from the user
+   * via the client-side `signIn` function.
+   *
+   * @returns This method expects a user ID to be returned for a successful login.
+   * A session ID can be also returned and that session will be used.
+   * If an error is thrown or `null` is returned, the sign-in will fail.
+   */
+  authorize: (
+    /**
+     * The available keys are determined by your call to `signIn()` on the client.
+     *
+     * You can add basic validation depending on your use case,
+     * or you can use a popular library like [Zod](https://zod.dev) for validating
+     * the input.
+     */
+    credentials: Partial<Record<string, Value | undefined>>,
+    ctx: GenericActionCtxWithAuthConfig<DataModel>,
+  ) => Promise<{
+    userId: GenericId<"user">;
+    sessionId?: GenericId<"session">;
+  } | null>;
+  /**
+   * Provide hashing and verification functions if you're
+   * storing account secrets and want to control
+   * how they're hashed.
+   *
+   * These functions will be called during
+   * the `createAccount` and `retrieveAccount` execution when the
+   * `secret` option is used.
+   */
+  crypto?: {
+    /**
+     * Function used to hash the secret.
+     */
+    hashSecret: (secret: string) => Promise<string>;
+    /**
+     * Function used to verify that the secret
+     * matches the stored hash.
+     */
+    verifySecret: (secret: string, hash: string) => Promise<boolean>;
+  };
+  /**
+   * Register extra providers used in the implementation of the credentials
+   * provider. They will only be available to the `signInViaProvider`
+   * function, and not to the `signIn` function exposed to clients.
+   */
+  extraProviders?: (AuthProviderConfig | undefined)[];
+}
+
+/**
+ * The Credentials provider allows you to handle signing in with arbitrary credentials,
+ * such as a username and password, domain, or two factor authentication or hardware device (e.g. YubiKey U2F / FIDO).
+ */
+export default function convexCredentials<DataModel extends GenericDataModel>(
+  config: ConvexCredentialsUserConfig<DataModel>,
+): ConvexCredentialsConfig {
+  return {
+    id: "credentials",
+    type: "credentials",
+    authorize: async () => null,
+    // @ts-expect-error Internal
+    options: config,
+  };
+}

package/src/providers/Email.ts

@@ -0,0 +1,60 @@
+/**
+ * Simplifies creating custom email providers, such as for sending OTPs.
+ *
+ * @module
+ */
+
+import { GenericDataModel } from "convex/server";
+import { EmailConfig, EmailUserConfig } from "../server/types.js";
+
+/**
+ * Email providers send a token to the user's email address
+ * for sign-in.
+ *
+ * When you use this function to create your config, by default it
+ * checks that there is an `email` field during token verification
+ * that matches the `email` used during the initial `signIn` call.
+ *
+ * If you want the "magic link behavior", where only the token is needed,
+ * you can override the `authorize` method to skip the check:
+ *
+ * ```ts
+ * import Email from "@robelest/convex-auth/providers/Email";
+ * import { convexAuth } from "@robelest/convex-auth/component";
+ *
+ * export const { auth, signIn, signOut, store } = convexAuth({
+ *   providers: [
+ *     Email({ authorize: undefined }),
+ *   ],
+ * });
+ * ```
+ *
+ * Make sure the token has high enough entropy to be secure.
+ */
+export function Email<DataModel extends GenericDataModel>(
+  config: EmailUserConfig<DataModel> &
+    Pick<EmailConfig, "sendVerificationRequest">,
+): EmailConfig<DataModel> {
+  return {
+    id: "email",
+    type: "email",
+    name: "Email",
+    from: "Auth.js <no-reply@authjs.dev>",
+    maxAge: 60 * 60, // 1 hour
+    authorize: async (params, account) => {
+      if (typeof params.email !== "string") {
+        throw new Error(
+          "Token verification requires an `email` in params of `signIn`.",
+        );
+      }
+      if (account.providerAccountId !== params.email) {
+        throw new Error(
+          "Short verification code requires a matching `email` " +
+            "in params of `signIn`.",
+        );
+      }
+    },
+    sendVerificationRequest: config.sendVerificationRequest,
+    options: config,
+  };
+}

package/src/providers/Password.ts

@@ -0,0 +1,253 @@
+/**
+ * Configure {@link Password} provider given a {@link PasswordConfig}.
+ *
+ * The `Password` provider supports the following flows, determined
+ * by the `flow` parameter:
+ *
+ * - `"signUp"`: Create a new account with a password.
+ * - `"signIn"`: Sign in with an existing account and password.
+ * - `"reset"`: Request a password reset.
+ * - `"reset-verification"`: Verify a password reset code and change password.
+ * - `"email-verification"`: If email verification is enabled and `code` is
+ *    included in params, verify an OTP.
+ *
+ * ```ts
+ * import Password from "@robelest/convex-auth/providers/Password";
+ * import { convexAuth } from "@robelest/convex-auth/component";
+ *
+ * export const { auth, signIn, signOut, store } = convexAuth({
+ *   providers: [Password],
+ * });
+ * ```
+ *
+ * @module
+ */
+
+import convexCredentials, {
+  ConvexCredentialsUserConfig,
+} from "@robelest/convex-auth/providers/ConvexCredentials";
+import {
+  EmailConfig,
+  GenericActionCtxWithAuthConfig,
+  GenericDoc,
+  createAccount,
+  invalidateSessions,
+  modifyAccountCredentials,
+  retrieveAccount,
+  signInViaProvider,
+} from "@robelest/convex-auth/component";
+import {
+  DocumentByName,
+  GenericDataModel,
+  WithoutSystemFields,
+} from "convex/server";
+import { Value } from "convex/values";
+import { Scrypt } from "lucia";
+
+/**
+ * The available options to a {@link Password} provider for Convex Auth.
+ */
+export interface PasswordConfig<DataModel extends GenericDataModel> {
+  /**
+   * Uniquely identifies the provider, allowing to use
+   * multiple different {@link Password} providers.
+   */
+  id?: string;
+  /**
+   * Perform checks on provided params and customize the user
+   * information stored after sign up, including email normalization.
+   *
+   * Called for every flow ("signUp", "signIn", "reset",
+   * "reset-verification" and "email-verification").
+   */
+  profile?: (
+    /**
+     * The values passed to the `signIn` function.
+     */
+    params: Record<string, Value | undefined>,
+    /**
+     * Convex ActionCtx in case you want to read from or write to
+     * the database.
+     */
+    ctx: GenericActionCtxWithAuthConfig<DataModel>,
+  ) => WithoutSystemFields<DocumentByName<DataModel, "user">> & {
+    email: string;
+  };
+  /**
+   * Performs custom validation on password provided during sign up or reset.
+   *
+   * Otherwise the default validation is used (password is not empty and
+   * at least 8 characters in length).
+   *
+   * If the provided password is invalid, implementations must throw an Error.
+   *
+   * @param password the password supplied during "signUp" or
+   *                 "reset-verification" flows.
+   */
+  validatePasswordRequirements?: (password: string) => void;
+  /**
+   * Provide hashing and verification functions if you want to control
+   * how passwords are hashed.
+   */
+  crypto?: ConvexCredentialsUserConfig["crypto"];
+  /**
+   * An Auth.js email provider used to require verification
+   * before password reset.
+   */
+  reset?: EmailConfig | ((...args: any) => EmailConfig);
+  /**
+   * An Auth.js email provider used to require verification
+   * before sign up / sign in.
+   */
+  verify?: EmailConfig | ((...args: any) => EmailConfig);
+}
+
+/**
+ * Email and password authentication provider.
+ *
+ * Passwords are by default hashed using Scrypt from Lucia.
+ * You can customize the hashing via the `crypto` option.
+ *
+ * Email verification is not required unless you pass
+ * an email provider to the `verify` option.
+ */
+export default function password<DataModel extends GenericDataModel>(
+  config: PasswordConfig<DataModel> = {},
+) {
+  const provider = config.id ?? "password";
+  return convexCredentials<DataModel>({
+    id: "password",
+    authorize: async (params, ctx) => {
+      const flow = params.flow as string;
+      const passwordToValidate =
+        flow === "signUp"
+          ? (params.password as string)
+          : flow === "reset-verification"
+            ? (params.newPassword as string)
+            : null;
+      if (passwordToValidate !== null) {
+        if (config.validatePasswordRequirements !== undefined) {
+          config.validatePasswordRequirements(passwordToValidate);
+        } else {
+          validateDefaultPasswordRequirements(passwordToValidate);
+        }
+      }
+      const profile = config.profile?.(params, ctx) ?? defaultProfile(params);
+      const { email } = profile;
+      const secret = params.password as string;
+      let account: GenericDoc<DataModel, "account">;
+      let user: GenericDoc<DataModel, "user">;
+      if (flow === "signUp") {
+        if (secret === undefined) {
+          throw new Error("Missing `password` param for `signUp` flow");
+        }
+        const created = await createAccount(ctx, {
+          provider,
+          account: { id: email, secret },
+          profile: profile as any,
+          shouldLinkViaEmail: config.verify !== undefined,
+          shouldLinkViaPhone: false,
+        });
+        ({ account, user } = created);
+      } else if (flow === "signIn") {
+        if (secret === undefined) {
+          throw new Error("Missing `password` param for `signIn` flow");
+        }
+        const retrieved = await retrieveAccount(ctx, {
+          provider,
+          account: { id: email, secret },
+        });
+        if (retrieved === null) {
+          throw new Error("Invalid credentials");
+        }
+        ({ account, user } = retrieved);
+        // START: Optional, support password reset
+      } else if (flow === "reset") {
+        if (!config.reset) {
+          throw new Error(`Password reset is not enabled for ${provider}`);
+        }
+        const { account } = await retrieveAccount(ctx, {
+          provider,
+          account: { id: email },
+        });
+        return await signInViaProvider(ctx, config.reset, {
+          accountId: account._id,
+          params,
+        });
+      } else if (flow === "reset-verification") {
+        if (!config.reset) {
+          throw new Error(`Password reset is not enabled for ${provider}`);
+        }
+        if (params.newPassword === undefined) {
+          throw new Error(
+            "Missing `newPassword` param for `reset-verification` flow",
+          );
+        }
+        const result = await signInViaProvider(ctx, config.reset, { params });
+        if (result === null) {
+          throw new Error("Invalid code");
+        }
+        const { userId, sessionId } = result;
+        const secret = params.newPassword as string;
+        await modifyAccountCredentials(ctx, {
+          provider,
+          account: { id: email, secret },
+        });
+        await invalidateSessions(ctx, { userId, except: [sessionId] });
+        return { userId, sessionId };
+        // END
+        // START: Optional, email verification during sign in
+      } else if (flow === "email-verification") {
+        if (!config.verify) {
+          throw new Error(`Email verification is not enabled for ${provider}`);
+        }
+        const { account } = await retrieveAccount(ctx, {
+          provider,
+          account: { id: email },
+        });
+        return await signInViaProvider(ctx, config.verify, {
+          accountId: account._id,
+          params,
+        });
+        // END
+      } else {
+        throw new Error(
+          "Missing `flow` param, it must be one of " +
+            '"signUp", "signIn", "reset", "reset-verification" or ' +
+            '"email-verification"!',
+        );
+      }
+      // START: Optional, email verification during sign in
+      if (config.verify && !account.emailVerified) {
+        return await signInViaProvider(ctx, config.verify, {
+          accountId: account._id,
+          params,
+        });
+      }
+      // END
+      return { userId: user._id };
+    },
+    crypto: {
+      async hashSecret(password: string) {
+        return await new Scrypt().hash(password);
+      },
+      async verifySecret(password: string, hash: string) {
+        return await new Scrypt().verify(hash, password);
+      },
+    },
+    extraProviders: [config.reset, config.verify],
+    ...config,
+  });
+}
+
+function validateDefaultPasswordRequirements(password: string) {
+  if (!password || password.length < 8) {
+    throw new Error("Invalid password");
+  }
+}
+
+function defaultProfile(params: Record<string, unknown>) {
+  return {
+    email: params.email as string,
+  };
+}

package/src/providers/Phone.ts

@@ -0,0 +1,46 @@
+/**
+ * Configure {@link Phone} provider given a {@link PhoneUserConfig}.
+ *
+ * Simplifies creating phone providers.
+ *
+ * By default checks that there is an `phone` field during token verification
+ * that matches the `phone` used during the initial `signIn` call.
+ *
+ * @module
+ */
+
+import { GenericDataModel } from "convex/server";
+import { PhoneConfig, PhoneUserConfig } from "../server/types.js";
+
+/**
+ * Phone providers send a token to the user's phone number
+ * for sign-in.
+ *
+ * When you use this function to create your config, it
+ * checks that there is a `phone` field during token verification
+ * that matches the `phone` used during the initial `signIn` call.
+ */
+export default function phone<DataModel extends GenericDataModel>(
+  config: PhoneUserConfig & Pick<PhoneConfig, "sendVerificationRequest">,
+): PhoneConfig<DataModel> {
+  return {
+    id: "phone",
+    type: "phone",
+    maxAge: 60 * 20, // 20 minutes
+    authorize: async (params, account) => {
+      if (typeof params.phone !== "string") {
+        throw new Error(
+          "Token verification requires an `phone` in params of `signIn`.",
+        );
+      }
+      if (account.providerAccountId !== params.phone) {
+        throw new Error(
+          "Short verification code requires a matching `phone` " +
+            "in params of `signIn`.",
+        );
+      }
+    },
+    sendVerificationRequest: config.sendVerificationRequest,
+    options: config,
+  };
+}

package/src/server/convex_types.ts

@@ -0,0 +1,55 @@
+import {
+  DocumentByName,
+  FunctionReference,
+  GenericDataModel,
+  RegisteredAction,
+  RegisteredMutation,
+  RegisteredQuery,
+  TableNamesInDataModel,
+} from "convex/server";
+import { GenericId } from "convex/values";
+
+/**
+ * Convex document from a given table.
+ */
+export type GenericDoc<
+  DataModel extends GenericDataModel,
+  TableName extends TableNamesInDataModel<DataModel>,
+> = DocumentByName<DataModel, TableName> & {
+  _id: GenericId<TableName>;
+  _creationTime: number;
+};
+
+/**
+ * @internal
+ */
+export type FunctionReferenceFromExport<Export> =
+  Export extends RegisteredQuery<infer Visibility, infer Args, infer Output>
+    ? FunctionReference<"query", Visibility, Args, ConvertReturnType<Output>>
+    : Export extends RegisteredMutation<
+          infer Visibility,
+          infer Args,
+          infer Output
+        >
+      ? FunctionReference<
+          "mutation",
+          Visibility,
+          Args,
+          ConvertReturnType<Output>
+        >
+      : Export extends RegisteredAction<
+            infer Visibility,
+            infer Args,
+            infer Output
+          >
+        ? FunctionReference<
+            "action",
+            Visibility,
+            Args,
+            ConvertReturnType<Output>
+          >
+        : never;
+
+type ConvertReturnType<T> = UndefinedToNull<Awaited<T>>;
+
+type UndefinedToNull<T> = T extends void ? null : T;

package/src/server/cookies.ts

@@ -0,0 +1,42 @@
+import { isLocalHost } from "./utils.js";
+
+export const SHARED_COOKIE_OPTIONS = {
+  httpOnly: true,
+  sameSite: "none" as const,
+  secure: true,
+  path: "/",
+  partitioned: true,
+};
+
+const REDIRECT_MAX_AGE = 60 * 15; // 15 minutes in seconds
+export function redirectToParamCookie(providerId: string, redirectTo: string) {
+  return {
+    name: redirectToParamCookieName(providerId),
+    value: redirectTo,
+    options: { ...SHARED_COOKIE_OPTIONS, maxAge: REDIRECT_MAX_AGE },
+  };
+}
+
+export function useRedirectToParam(
+  providerId: string,
+  cookies: Record<string, string | undefined>,
+) {
+  const cookieName = redirectToParamCookieName(providerId);
+  const redirectTo = cookies[cookieName];
+  if (redirectTo === undefined) {
+    return null;
+  }
+
+  // Clear the cookie
+  const updatedCookie = {
+    name: cookieName,
+    value: "",
+    options: { ...SHARED_COOKIE_OPTIONS, maxAge: 0 },
+  };
+
+  return { redirectTo, updatedCookie };
+}
+
+function redirectToParamCookieName(providerId: string) {
+  return (!isLocalHost(process.env.CONVEX_SITE_URL) ? "__Host-" : "") + providerId + "RedirectTo";
+}

package/src/server/implementation/db.ts

@@ -0,0 +1,125 @@
+import { GenericActionCtx, GenericDataModel, GenericMutationCtx } from "convex/server";
+import { AuthComponentApi } from "../types.js";
+
+type MutationCtxLike = Pick<GenericMutationCtx<GenericDataModel>, "runQuery" | "runMutation">;
+type ActionCtxLike = Pick<
+  GenericActionCtx<GenericDataModel>,
+  "runQuery" | "runMutation" | "runAction"
+>;
+
+type CtxLike = MutationCtxLike | ActionCtxLike;
+
+export type AuthDb = ReturnType<typeof createAuthDb>;
+
+export function createAuthDb(ctx: CtxLike, component: AuthComponentApi) {
+  return {
+    users: {
+      getById: (userId: string) =>
+        ctx.runQuery(component.public.userGetById, { userId }),
+      findByVerifiedEmail: (email: string) =>
+        ctx.runQuery(component.public.userFindByVerifiedEmail, { email }),
+      findByVerifiedPhone: (phone: string) =>
+        ctx.runQuery(component.public.userFindByVerifiedPhone, { phone }),
+      insert: (data: Record<string, unknown>) =>
+        ctx.runMutation(component.public.userInsert, { data }) as Promise<string>,
+      patch: (userId: string, data: Record<string, unknown>) =>
+        ctx.runMutation(component.public.userPatch, { userId, data }),
+      upsert: (userId: string | undefined, data: Record<string, unknown>) =>
+        ctx.runMutation(component.public.userUpsert, { userId, data }) as Promise<string>,
+    },
+    accounts: {
+      get: (provider: string, providerAccountId: string) =>
+        ctx.runQuery(component.public.accountGet, { provider, providerAccountId }),
+      getById: (accountId: string) =>
+        ctx.runQuery(component.public.accountGetById, { accountId }),
+      create: (args: {
+        userId: string;
+        provider: string;
+        providerAccountId: string;
+        secret?: string;
+      }) => ctx.runMutation(component.public.accountInsert, args) as Promise<string>,
+      patch: (accountId: string, data: Record<string, unknown>) =>
+        ctx.runMutation(component.public.accountPatch, { accountId, data }),
+      delete: (accountId: string) =>
+        ctx.runMutation(component.public.accountDelete, { accountId }),
+    },
+    sessions: {
+      create: (userId: string, expirationTime: number) =>
+        ctx.runMutation(component.public.sessionCreate, { userId, expirationTime }) as Promise<string>,
+      getById: (sessionId: string) =>
+        ctx.runQuery(component.public.sessionGetById, { sessionId }),
+      delete: (sessionId: string) =>
+        ctx.runMutation(component.public.sessionDelete, { sessionId }),
+      listByUser: (userId: string) =>
+        ctx.runQuery(component.public.sessionListByUser, { userId }),
+    },
+    verifiers: {
+      create: (sessionId?: string) =>
+        ctx.runMutation(component.public.verifierCreate, { sessionId }) as Promise<string>,
+      getById: (verifierId: string) =>
+        ctx.runQuery(component.public.verifierGetById, { verifierId }),
+      getBySignature: (signature: string) =>
+        ctx.runQuery(component.public.verifierGetBySignature, { signature }),
+      patch: (verifierId: string, data: Record<string, unknown>) =>
+        ctx.runMutation(component.public.verifierPatch, { verifierId, data }),
+      delete: (verifierId: string) =>
+        ctx.runMutation(component.public.verifierDelete, { verifierId }),
+    },
+    verificationCodes: {
+      getByAccountId: (accountId: string) =>
+        ctx.runQuery(component.public.verificationCodeGetByAccountId, { accountId }),
+      getByCode: (code: string) =>
+        ctx.runQuery(component.public.verificationCodeGetByCode, { code }),
+      create: (args: {
+        accountId: string;
+        provider: string;
+        code: string;
+        expirationTime: number;
+        verifier?: string;
+        emailVerified?: string;
+        phoneVerified?: string;
+      }) =>
+        ctx.runMutation(component.public.verificationCodeCreate, args),
+      delete: (verificationCodeId: string) =>
+        ctx.runMutation(component.public.verificationCodeDelete, {
+          verificationCodeId,
+        }),
+    },
+    refreshTokens: {
+      create: (args: {
+        sessionId: string;
+        expirationTime: number;
+        parentRefreshTokenId?: string;
+      }) =>
+        ctx.runMutation(component.public.refreshTokenCreate, args) as Promise<string>,
+      getById: (refreshTokenId: string) =>
+        ctx.runQuery(component.public.refreshTokenGetById, { refreshTokenId }),
+      patch: (refreshTokenId: string, data: Record<string, unknown>) =>
+        ctx.runMutation(component.public.refreshTokenPatch, { refreshTokenId, data }),
+      getChildren: (sessionId: string, parentRefreshTokenId: string) =>
+        ctx.runQuery(component.public.refreshTokenGetChildren, {
+          sessionId,
+          parentRefreshTokenId,
+        }),
+      listBySession: (sessionId: string) =>
+        ctx.runQuery(component.public.refreshTokenListBySession, { sessionId }),
+      deleteAll: (sessionId: string) =>
+        ctx.runMutation(component.public.refreshTokenDeleteAll, { sessionId }),
+      getActive: (sessionId: string) =>
+        ctx.runQuery(component.public.refreshTokenGetActive, { sessionId }),
+    },
+    rateLimits: {
+      get: (identifier: string) =>
+        ctx.runQuery(component.public.rateLimitGet, { identifier }),
+      create: (args: {
+        identifier: string;
+        attemptsLeft: number;
+        lastAttemptTime: number;
+      }) => ctx.runMutation(component.public.rateLimitCreate, args),
+      patch: (rateLimitId: string, data: Record<string, unknown>) =>
+        ctx.runMutation(component.public.rateLimitPatch, { rateLimitId, data }),
+      delete: (rateLimitId: string) =>
+        ctx.runMutation(component.public.rateLimitDelete, { rateLimitId }),
+    },
+  };
+}