@robelest/convex-auth 0.0.1

package/src/server/provider_utils.ts

@@ -0,0 +1,222 @@
+// Some code adapted from Auth.js. Original license:
+//
+// ISC License
+//
+// Copyright (c) 2022-2024, Balázs Orbán
+//
+// Permission to use, copy, modify, and/or distribute this software for any
+// purpose with or without fee is hereby granted, provided that the above
+// copyright notice and this permission notice appear in all copies.
+//
+// THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+// WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+// MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+// ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+// WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+// ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+// OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+import { setEnvDefaults } from "@auth/core";
+import {
+  AccountCallback,
+  OAuth2Config,
+  OAuthConfig,
+  OAuthEndpointType,
+  OIDCConfig,
+  ProfileCallback,
+} from "@auth/core/providers";
+import { Profile } from "@auth/core/types";
+import {
+  AuthProviderConfig,
+  AuthProviderMaterializedConfig,
+  ConvexAuthConfig,
+} from "./types.js";
+
+/**
+ * @internal
+ */
+export function configDefaults(config_: ConvexAuthConfig) {
+  const config = materializeAndDefaultProviders(config_);
+  // Collect extra providers
+  const extraProviders = config.providers
+    .filter((p) => p.type === "credentials")
+    .map((p) => p.extraProviders)
+    .flat()
+    .filter((p) => p !== undefined);
+  return {
+    ...config,
+    extraProviders: materializeProviders(extraProviders),
+    theme: config.theme ?? {
+      colorScheme: "auto",
+      logo: "",
+      brandColor: "",
+      buttonText: "",
+    },
+  };
+}
+
+/**
+ * @internal
+ */
+export function materializeProvider(provider: AuthProviderConfig) {
+  const config = { providers: [provider] };
+  materializeAndDefaultProviders(config);
+  return config.providers[0] as AuthProviderMaterializedConfig;
+}
+
+function materializeProviders(providers: AuthProviderConfig[]) {
+  const config = { providers };
+  materializeAndDefaultProviders(config);
+  return config.providers as AuthProviderMaterializedConfig[];
+}
+
+function materializeAndDefaultProviders(config_: ConvexAuthConfig) {
+  // Have to materialize first so that the correct env variables are used
+  const providers = config_.providers.map((provider) =>
+    providerDefaults(
+      typeof provider === "function" ? provider() : (provider as any),
+    ),
+  );
+  const config = { ...config_, providers };
+
+  // Unfortunately mutates its argument
+  setEnvDefaults(process.env, config as any);
+  // Manually do this for new provider type
+  config.providers.forEach((provider) => {
+    if (provider.type === "phone") {
+      const ID = provider.id.toUpperCase().replace(/-/g, "_");
+      // Should not require this env var at push time, as the provider's
+      // implementation might not use it
+      provider.apiKey ??= process.env[`AUTH_${ID}_KEY`];
+    }
+  });
+  return config;
+}
+
+function providerDefaults(provider: AuthProviderMaterializedConfig) {
+  // TODO: Add `redirectProxyUrl` to oauth providers
+  const merged = merge(
+    provider,
+    (provider as any).options,
+  ) as AuthProviderMaterializedConfig;
+  return merged.type === "oauth" || merged.type === "oidc"
+    ? normalizeOAuth(merged)
+    : merged;
+}
+
+const defaultProfile: ProfileCallback<Profile> = (profile) => {
+  return stripUndefined({
+    id: profile.sub ?? profile.id ?? crypto.randomUUID(),
+    name: profile.name ?? profile.nickname ?? profile.preferred_username,
+    email: profile.email ?? undefined,
+    image: profile.picture ?? undefined,
+  });
+};
+
+const defaultAccount: AccountCallback = (account) => {
+  return stripUndefined({
+    access_token: account.access_token,
+    id_token: account.id_token,
+    refresh_token: account.refresh_token,
+    expires_at: account.expires_at,
+    scope: account.scope,
+    token_type: account.token_type,
+    session_state: account.session_state,
+  });
+};
+
+function stripUndefined<T extends object>(o: T): T {
+  const result = {} as any;
+  for (const [k, v] of Object.entries(o)) v !== undefined && (result[k] = v);
+  return result as T;
+}
+
+function normalizeOAuth<T extends OIDCConfig<any> | OAuth2Config<any>>(
+  c: T,
+): T {
+  if (c.issuer) c.wellKnown ??= `${c.issuer}/.well-known/openid-configuration`;
+
+  const checks = c.checks ?? ["pkce"];
+  if (c.redirectProxyUrl) {
+    if (!checks.includes("state")) checks.push("state");
+    c.redirectProxyUrl = `${c.redirectProxyUrl}/callback/${c.id}`;
+  }
+
+  return {
+    ...c,
+    checks,
+    profile: c.profile ?? defaultProfile,
+    account: c.account ?? defaultAccount,
+  };
+}
+
+export const PLACEHOLDER_URL_HOST = "convexauth.mumbojumbo";
+
+const PLACEHOLDER_URL = `https://${PLACEHOLDER_URL_HOST}`;
+
+export function normalizeEndpoint(
+  e?: OAuthConfig<any>[OAuthEndpointType],
+  issuer?: string,
+) {
+  if (!e && issuer) return undefined;
+  if (typeof e === "string") {
+    return { url: new URL(e) };
+  }
+  // Placeholder URL is used to pass around the URL object
+  // even if the URL hasn't been specified: the `issuer`
+  // is used instead.
+  const url = new URL(e?.url ?? PLACEHOLDER_URL);
+  if (e?.params != null) {
+    for (const [key, value] of Object.entries(e.params)) {
+      url.searchParams.set(
+        key,
+        String(key === "claims" ? JSON.stringify(value) : value),
+      );
+    }
+  }
+  return { url, request: e?.request, conform: e?.conform };
+}
+
+// Source: https://stackoverflow.com/a/34749873/5364135
+
+/**
+ * Deep merge two objects
+ *
+ * @internal
+ */
+export function merge(target: any, ...sources: any[]): any {
+  if (!sources.length) return target;
+  const source = sources.shift();
+
+  if (isObject(target) && isObject(source)) {
+    for (const key in source) {
+      if (isObject(source[key])) {
+        if (!target[key]) Object.assign(target, { [key]: {} });
+        merge(target[key], source[key]);
+      } else {
+        Object.assign(target, { [key]: source[key] });
+      }
+    }
+  }
+
+  return merge(target, ...sources);
+}
+
+/** Simple object check */
+function isObject(item: any): boolean {
+  return item && typeof item === "object" && !Array.isArray(item);
+}
+/**
+ * @internal
+ */
+export function listAvailableProviders(
+  config: ReturnType<typeof configDefaults>,
+  allowExtraProviders: boolean,
+) {
+  const availableProviders = config.providers
+    .concat(allowExtraProviders ? config.extraProviders : [])
+    .map((provider) => `\`${provider.id}\``);
+  return availableProviders.length > 0
+    ? availableProviders.join(", ")
+    : "no providers have been configured";
+}

package/src/server/types.ts

@@ -0,0 +1,470 @@
+import {
+  Provider as AuthjsProviderConfig,
+  CredentialsConfig,
+  EmailConfig as AuthjsEmailConfig,
+  OAuth2Config,
+  OIDCConfig,
+} from "@auth/core/providers";
+import { Theme } from "@auth/core/types";
+import {
+  AnyDataModel,
+  FunctionReference,
+  GenericActionCtx,
+  GenericDataModel,
+  GenericMutationCtx,
+} from "convex/server";
+import { GenericId, Value } from "convex/values";
+import { ConvexCredentialsUserConfig } from "../providers/ConvexCredentials.js";
+import { GenericDoc } from "./convex_types.js";
+
+/**
+ * The config for the Convex Auth library, passed to `convexAuth`.
+ */
+export type ConvexAuthConfig = {
+  /**
+   * A list of authentication provider configs.
+   *
+   * You can import existing configs from
+   * - `@auth/core/providers/<provider-name>`
+   * - `@robelest/convex-auth/providers/<provider-name>`
+   */
+  providers: AuthProviderConfig[];
+  /**
+   * Optional auth component reference from `components.auth`.
+   *
+   * When provided, core auth storage operations are executed through
+   * the component API boundary instead of direct table access.
+   */
+  component?: AuthComponentApi;
+  /**
+   * Theme used for emails.
+   * See [Auth.js theme docs](https://authjs.dev/reference/core/types#theme).
+   */
+  theme?: Theme;
+  /**
+   * Session configuration.
+   */
+  session?: {
+    /**
+     * How long can a user session last without the user reauthenticating.
+     *
+     * Defaults to 30 days.
+     */
+    totalDurationMs?: number;
+    /**
+     * How long can a user session last without the user being active.
+     *
+     * Defaults to 30 days.
+     */
+    inactiveDurationMs?: number;
+  };
+  /**
+   * JWT configuration.
+   */
+  jwt?: {
+    /**
+     * How long is the JWT valid for after it is signed initially.
+     *
+     * Defaults to 1 hour.
+     */
+    durationMs?: number;
+  };
+  /**
+   * Sign-in configuration.
+   */
+  signIn?: {
+    /**
+     * How many times can the user fail to provide the correct credentials
+     * (password, OTP) per hour.
+     *
+     * Defaults to 10 times per hour (that is 10 failed attempts, and then
+     * allow another one every 6 minutes).
+     */
+    maxFailedAttempsPerHour?: number;
+  };
+  callbacks?: {
+    /**
+     * Control which URLs are allowed as a destination after OAuth sign-in
+     * and for magic links:
+     *
+     * ```ts
+     * import GitHub from "@auth/core/providers/github";
+     * import { convexAuth } from "@robelest/convex-auth/component";
+     *
+     * export const { auth, signIn, signOut, store } = convexAuth({
+     *   providers: [GitHub],
+     *   callbacks: {
+     *     async redirect({ redirectTo }) {
+     *       // Check that `redirectTo` is valid
+     *       // and return the relative or absolute URL
+     *       // to redirect to.
+     *     },
+     *   },
+     * });
+     * ```
+     *
+     * Convex Auth performs redirect only during OAuth sign-in. By default,
+     * it redirects back to the URL specified via the `SITE_URL` environment
+     * variable. Similarly magic links link to `SITE_URL`.
+     *
+     * You can customize that behavior by providing a `redirectTo` param
+     * to the `signIn` function:
+     *
+     * ```ts
+     * signIn("google", { redirectTo: "/dashboard" })
+     * ```
+     *
+     * You can even redirect to a different site.
+     *
+     * This callback, if specified, is then called with the provided
+     * `redirectTo` param. Otherwise, only query params, relative paths
+     * and URLs starting with `SITE_URL` are allowed.
+     */
+    redirect?: (params: {
+      /**
+       * The param value passed to the `signIn` function.
+       */
+      redirectTo: string;
+    }) => Promise<string>;
+    /**
+     * Completely control account linking via this callback.
+     *
+     * This callback is called during the sign-in process,
+     * before account creation and token generation.
+     * If specified, this callback is responsible for creating
+     * or updating the user document.
+     *
+     * For "credentials" providers, the callback is only called
+     * when `createAccount` is called.
+     */
+    createOrUpdateUser?: (
+      ctx: GenericMutationCtx<AnyDataModel>,
+      args: {
+        /**
+         * If this is a sign-in to an existing account,
+         * this is the existing user ID linked to that account.
+         */
+        existingUserId: GenericId<"user"> | null;
+        /**
+         * The provider type or "verification" if this callback is called
+         * after an email or phone token verification.
+         */
+        type: "oauth" | "credentials" | "email" | "phone" | "verification";
+        /**
+         * The provider used for the sign-in, or the provider
+         * tied to the account which is having the email or phone verified.
+         */
+        provider: AuthProviderMaterializedConfig;
+        /**
+         * - The profile returned by the OAuth provider's `profile` method.
+         * - The profile passed to `createAccount` from a ConvexCredentials
+         * config.
+         * - The email address to which an email will be sent.
+         * - The phone number to which a text will be sent.
+         */
+        profile: Record<string, unknown> & {
+          email?: string;
+          phone?: string;
+          emailVerified?: boolean;
+          phoneVerified?: boolean;
+        };
+        /**
+         * The `shouldLink` argument passed to `createAccount`.
+         */
+        shouldLink?: boolean;
+      },
+    ) => Promise<GenericId<"user">>;
+    /**
+     * Perform additional writes after a user is created.
+     *
+     * This callback is called during the sign-in process,
+     * after the user is created or updated,
+     * before account creation and token generation.
+     *
+     * **This callback is only called if `createOrUpdateUser`
+     * is not specified.** If `createOrUpdateUser` is specified,
+     * you can perform any additional writes in that callback.
+     *
+     * For "credentials" providers, the callback is only called
+     * when `createAccount` is called.
+     */
+    afterUserCreatedOrUpdated?: (
+      ctx: GenericMutationCtx<AnyDataModel>,
+      args: {
+        /**
+         * The ID of the user that is being signed in.
+         */
+        userId: GenericId<"user">;
+        /**
+         * If this is a sign-in to an existing account,
+         * this is the existing user ID linked to that account.
+         */
+        existingUserId: GenericId<"user"> | null;
+        /**
+         * The provider type or "verification" if this callback is called
+         * after an email or phone token verification.
+         */
+        type: "oauth" | "credentials" | "email" | "phone" | "verification";
+        /**
+         * The provider used for the sign-in, or the provider
+         * tied to the account which is having the email or phone verified.
+         */
+        provider: AuthProviderMaterializedConfig;
+        /**
+         * - The profile returned by the OAuth provider's `profile` method.
+         * - The profile passed to `createAccount` from a ConvexCredentials
+         * config.
+         * - The email address to which an email will be sent.
+         * - The phone number to which a text will be sent.
+         */
+        profile: Record<string, unknown> & {
+          email?: string;
+          phone?: string;
+          emailVerified?: boolean;
+          phoneVerified?: boolean;
+        };
+        /**
+         * The `shouldLink` argument passed to `createAccount`.
+         */
+        shouldLink?: boolean;
+      },
+    ) => Promise<void>;
+  };
+};
+
+/**
+ * Same as Auth.js provider configs, but adds phone provider
+ * for verification via SMS or another phone-number-connected messaging
+ * service.
+ */
+export type AuthProviderConfig =
+  | Exclude<
+      AuthjsProviderConfig,
+      CredentialsConfig | ((...args: any) => CredentialsConfig)
+    >
+  | ConvexCredentialsConfig
+  | ((...args: any) => ConvexCredentialsConfig)
+  | PhoneConfig
+  | ((...args: any) => PhoneConfig);
+
+/**
+ * Extends the standard Auth.js email provider config
+ * to allow additional checks during token verification.
+ */
+export interface EmailConfig<
+  DataModel extends GenericDataModel = GenericDataModel,
+> extends AuthjsEmailConfig {
+  /**
+   * Before the token is verified, check other
+   * provided parameters.
+   *
+   * Used to make sure tha OTPs are accompanied
+   * with the correct email address.
+   */
+  authorize?: (
+    /**
+     * The values passed to the `signIn` function.
+     */
+    params: Record<string, Value | undefined>,
+    account: GenericDoc<DataModel, "account">,
+  ) => Promise<void>;
+}
+
+/**
+ * Configurable options for an email provider config.
+ */
+export type EmailUserConfig<
+  DataModel extends GenericDataModel = GenericDataModel,
+> = Omit<Partial<EmailConfig<DataModel>>, "options" | "type">;
+
+/**
+ * Same as email provider config, but verifies
+ * phone number instead of the email address.
+ */
+export interface PhoneConfig<
+  DataModel extends GenericDataModel = GenericDataModel,
+> {
+  id: string;
+  type: "phone";
+  /**
+   * Token expiration in seconds.
+   */
+  maxAge: number;
+  /**
+   * Send the phone number verification request.
+   */
+  sendVerificationRequest: (
+    params: {
+      identifier: string;
+      url: string;
+      expires: Date;
+      provider: PhoneConfig;
+      token: string;
+    },
+    ctx: GenericActionCtxWithAuthConfig<DataModel>,
+  ) => Promise<void>;
+  /**
+   * Defaults to `process.env.AUTH_<PROVIDER_ID>_KEY`.
+   */
+  apiKey?: string;
+  /**
+   * Override this to generate a custom token.
+   * Note that the tokens are assumed to be cryptographically secure.
+   * Any tokens shorter than 24 characters are assumed to not
+   * be secure enough on their own, and require providing
+   * the original `phone` used in the initial `signIn` call.
+   * @returns
+   */
+  generateVerificationToken?: () => Promise<string>;
+  /**
+   * Normalize the phone number.
+   * @param identifier Passed as `phone` in params of `signIn`.
+   * @returns The phone number used in `sendVerificationRequest`.
+   */
+  normalizeIdentifier?: (identifier: string) => string;
+  /**
+   * Before the token is verified, check other
+   * provided parameters.
+   *
+   * Used to make sure tha OTPs are accompanied
+   * with the correct phone number.
+   */
+  authorize?: (
+    /**
+     * The values passed to the `signIn` function.
+     */
+    params: Record<string, Value | undefined>,
+    account: GenericDoc<DataModel, "account">,
+  ) => Promise<void>;
+  options: PhoneUserConfig<DataModel>;
+}
+
+/**
+ * Configurable options for a phone provider config.
+ */
+export type PhoneUserConfig<
+  DataModel extends GenericDataModel = GenericDataModel,
+> = Omit<Partial<PhoneConfig<DataModel>>, "options" | "type">;
+
+/**
+ * Similar to Auth.js Credentials config.
+ */
+export type ConvexCredentialsConfig = ConvexCredentialsUserConfig<any> & {
+  type: "credentials";
+  id: string;
+};
+
+/**
+ * Your `ActionCtx` enriched with `ctx.auth.config` field with
+ * the config passed to `convexAuth`.
+ */
+export type GenericActionCtxWithAuthConfig<DataModel extends GenericDataModel> =
+  GenericActionCtx<DataModel> & {
+    auth: { config: ConvexAuthMaterializedConfig };
+  };
+
+/**
+ * The config for the Convex Auth library, passed to `convexAuth`,
+ * with defaults and initialized providers.
+ *
+ * See {@link ConvexAuthConfig}
+ */
+export type ConvexAuthMaterializedConfig = {
+  providers: AuthProviderMaterializedConfig[];
+  theme: Theme;
+} & Pick<
+  ConvexAuthConfig,
+  "component" | "session" | "jwt" | "signIn" | "callbacks"
+>;
+
+/**
+ * Materialized Auth.js provider config.
+ */
+export type AuthProviderMaterializedConfig =
+  | OIDCConfig<any>
+  | OAuth2Config<any>
+  | EmailConfig
+  | PhoneConfig
+  | ConvexCredentialsConfig;
+
+/**
+ * Component function references required by core auth runtime.
+ */
+export type AuthComponentApi = {
+  public: {
+    userGetById: FunctionReference<"query", "internal">;
+    userFindByVerifiedEmail: FunctionReference<"query", "internal">;
+    userFindByVerifiedPhone: FunctionReference<"query", "internal">;
+    userInsert: FunctionReference<"mutation", "internal">;
+    userUpsert: FunctionReference<"mutation", "internal">;
+    userPatch: FunctionReference<"mutation", "internal">;
+    accountGet: FunctionReference<"query", "internal">;
+    accountGetById: FunctionReference<"query", "internal">;
+    accountInsert: FunctionReference<"mutation", "internal">;
+    accountPatch: FunctionReference<"mutation", "internal">;
+    accountDelete: FunctionReference<"mutation", "internal">;
+    sessionCreate: FunctionReference<"mutation", "internal">;
+    sessionGetById: FunctionReference<"query", "internal">;
+    sessionDelete: FunctionReference<"mutation", "internal">;
+    sessionListByUser: FunctionReference<"query", "internal">;
+    verifierCreate: FunctionReference<"mutation", "internal">;
+    verifierGetById: FunctionReference<"query", "internal">;
+    verifierGetBySignature: FunctionReference<"query", "internal">;
+    verifierPatch: FunctionReference<"mutation", "internal">;
+    verifierDelete: FunctionReference<"mutation", "internal">;
+    verificationCodeGetByAccountId: FunctionReference<"query", "internal">;
+    verificationCodeGetByCode: FunctionReference<"query", "internal">;
+    verificationCodeCreate: FunctionReference<"mutation", "internal">;
+    verificationCodeDelete: FunctionReference<"mutation", "internal">;
+    verificationGetByAccountId?: FunctionReference<"query", "internal">;
+    verificationGetByCode?: FunctionReference<"query", "internal">;
+    verificationCreate?: FunctionReference<"mutation", "internal">;
+    verificationDelete?: FunctionReference<"mutation", "internal">;
+    refreshTokenCreate: FunctionReference<"mutation", "internal">;
+    refreshTokenGetById: FunctionReference<"query", "internal">;
+    refreshTokenPatch: FunctionReference<"mutation", "internal">;
+    refreshTokenGetChildren: FunctionReference<"query", "internal">;
+    refreshTokenListBySession: FunctionReference<"query", "internal">;
+    refreshTokenDeleteAll: FunctionReference<"mutation", "internal">;
+    refreshTokenGetActive: FunctionReference<"query", "internal">;
+    tokenCreate?: FunctionReference<"mutation", "internal">;
+    tokenGetById?: FunctionReference<"query", "internal">;
+    tokenPatch?: FunctionReference<"mutation", "internal">;
+    tokenGetChildren?: FunctionReference<"query", "internal">;
+    tokenListBySession?: FunctionReference<"query", "internal">;
+    tokenDeleteAll?: FunctionReference<"mutation", "internal">;
+    tokenGetActive?: FunctionReference<"query", "internal">;
+    rateLimitGet: FunctionReference<"query", "internal">;
+    rateLimitCreate: FunctionReference<"mutation", "internal">;
+    rateLimitPatch: FunctionReference<"mutation", "internal">;
+    rateLimitDelete: FunctionReference<"mutation", "internal">;
+    limitGet?: FunctionReference<"query", "internal">;
+    limitCreate?: FunctionReference<"mutation", "internal">;
+    limitPatch?: FunctionReference<"mutation", "internal">;
+    limitDelete?: FunctionReference<"mutation", "internal">;
+    organizationCreate?: FunctionReference<"mutation", "internal">;
+    organizationGet?: FunctionReference<"query", "internal">;
+    organizationList?: FunctionReference<"query", "internal">;
+    organizationUpdate?: FunctionReference<"mutation", "internal">;
+    organizationDelete?: FunctionReference<"mutation", "internal">;
+    teamCreate?: FunctionReference<"mutation", "internal">;
+    teamGet?: FunctionReference<"query", "internal">;
+    teamListByOrganization?: FunctionReference<"query", "internal">;
+    teamUpdate?: FunctionReference<"mutation", "internal">;
+    teamDelete?: FunctionReference<"mutation", "internal">;
+    teamRelationCreate?: FunctionReference<"mutation", "internal">;
+    teamRelationGet?: FunctionReference<"query", "internal">;
+    teamRelationListByParent?: FunctionReference<"query", "internal">;
+    teamRelationDelete?: FunctionReference<"mutation", "internal">;
+    memberAdd?: FunctionReference<"mutation", "internal">;
+    memberRemove?: FunctionReference<"mutation", "internal">;
+    memberList?: FunctionReference<"query", "internal">;
+    memberRoleSet?: FunctionReference<"mutation", "internal">;
+    memberRoleGet?: FunctionReference<"query", "internal">;
+    inviteCreate?: FunctionReference<"mutation", "internal">;
+    inviteGet?: FunctionReference<"query", "internal">;
+    inviteList?: FunctionReference<"query", "internal">;
+    inviteAccept?: FunctionReference<"mutation", "internal">;
+    inviteRevoke?: FunctionReference<"mutation", "internal">;
+  };
+};

package/src/server/utils.ts

@@ -0,0 +1,12 @@
+export function requireEnv(name: string) {
+  const value = process.env[name];
+  if (value === undefined) {
+    throw new Error(`Missing environment variable \`${name}\``);
+  }
+  return value;
+}
+
+export function isLocalHost(host?: string) {
+  return /(localhost|127\.0\.0\.1):\d+/.test(
+  host ?? "");
+}