@robelest/convex-auth 0.0.1

package/src/server/implementation/users.ts

@@ -0,0 +1,286 @@
+import { GenericId } from "convex/values";
+import { Doc, MutationCtx } from "./types.js";
+import { AuthProviderMaterializedConfig, ConvexAuthConfig } from "../types.js";
+import { LOG_LEVELS, logWithLevel } from "./utils.js";
+import { createAuthDb } from "./db.js";
+
+type CreateOrUpdateUserArgs = {
+  type: "oauth" | "credentials" | "email" | "phone" | "verification";
+  provider: AuthProviderMaterializedConfig;
+  profile: Record<string, unknown> & {
+    email?: string;
+    phone?: string;
+    emailVerified?: boolean;
+    phoneVerified?: boolean;
+  };
+  shouldLinkViaEmail?: boolean;
+  shouldLinkViaPhone?: boolean;
+};
+
+export async function upsertUserAndAccount(
+  ctx: MutationCtx,
+  sessionId: GenericId<"session"> | null,
+  account:
+    | { existingAccount: Doc<"account"> }
+    | {
+        providerAccountId: string;
+        secret?: string;
+      },
+  args: CreateOrUpdateUserArgs,
+  config: ConvexAuthConfig,
+): Promise<{
+  userId: GenericId<"user">;
+  accountId: GenericId<"account">;
+}> {
+  const userId = await defaultCreateOrUpdateUser(
+    ctx,
+    sessionId,
+    "existingAccount" in account ? account.existingAccount : null,
+    args,
+    config,
+  );
+  const accountId = await createOrUpdateAccount(ctx, userId, account, args, config);
+  return { userId, accountId };
+}
+
+async function defaultCreateOrUpdateUser(
+  ctx: MutationCtx,
+  existingSessionId: GenericId<"session"> | null,
+  existingAccount: Doc<"account"> | null,
+  args: CreateOrUpdateUserArgs,
+  config: ConvexAuthConfig,
+) {
+  logWithLevel(LOG_LEVELS.DEBUG, "defaultCreateOrUpdateUser args:", {
+    existingAccountId: existingAccount?._id,
+    existingSessionId,
+    args,
+  });
+  const existingUserId = existingAccount?.userId ?? null;
+  const authDb =
+    config.component !== undefined ? createAuthDb(ctx, config.component) : null;
+  if (config.callbacks?.createOrUpdateUser !== undefined) {
+    logWithLevel(LOG_LEVELS.DEBUG, "Using custom createOrUpdateUser callback");
+    return await config.callbacks.createOrUpdateUser(ctx, {
+      existingUserId,
+      ...args,
+    });
+  }
+
+  const {
+    provider,
+    profile: {
+      emailVerified: profileEmailVerified,
+      phoneVerified: profilePhoneVerified,
+      ...profile
+    },
+  } = args;
+  const emailVerified =
+    profileEmailVerified ??
+    ((provider.type === "oauth" || provider.type === "oidc") &&
+      provider.allowDangerousEmailAccountLinking !== false);
+  const phoneVerified = profilePhoneVerified ?? false;
+  const shouldLinkViaEmail =
+    args.shouldLinkViaEmail || emailVerified || provider.type === "email";
+  const shouldLinkViaPhone =
+    args.shouldLinkViaPhone || phoneVerified || provider.type === "phone";
+
+  let userId = existingUserId;
+  if (existingUserId === null) {
+    const existingUserWithVerifiedEmailId =
+      typeof profile.email === "string" && shouldLinkViaEmail
+        ? (await uniqueUserWithVerifiedEmail(ctx, profile.email, config))?._id ??
+          null
+        : null;
+
+    const existingUserWithVerifiedPhoneId =
+      typeof profile.phone === "string" && shouldLinkViaPhone
+        ? (await uniqueUserWithVerifiedPhone(ctx, profile.phone, config))?._id ??
+          null
+        : null;
+    // If there is both email and phone verified user
+    // already we can't link.
+    if (
+      existingUserWithVerifiedEmailId !== null &&
+      existingUserWithVerifiedPhoneId !== null
+    ) {
+      logWithLevel(
+        LOG_LEVELS.DEBUG,
+        `Found existing email and phone verified users, so not linking: email: ${existingUserWithVerifiedEmailId}, phone: ${existingUserWithVerifiedPhoneId}`,
+      );
+      userId = null;
+    } else if (existingUserWithVerifiedEmailId !== null) {
+      logWithLevel(
+        LOG_LEVELS.DEBUG,
+        `Found existing email verified user, linking: ${existingUserWithVerifiedEmailId}`,
+      );
+      userId = existingUserWithVerifiedEmailId;
+    } else if (existingUserWithVerifiedPhoneId !== null) {
+      logWithLevel(
+        LOG_LEVELS.DEBUG,
+        `Found existing phone verified user, linking: ${existingUserWithVerifiedPhoneId}`,
+      );
+      userId = existingUserWithVerifiedPhoneId;
+    } else {
+      logWithLevel(
+        LOG_LEVELS.DEBUG,
+        "No existing verified users found, creating new user",
+      );
+      userId = null;
+    }
+  }
+  const userData = {
+    ...(emailVerified ? { emailVerificationTime: Date.now() } : null),
+    ...(phoneVerified ? { phoneVerificationTime: Date.now() } : null),
+    ...profile,
+  };
+  const existingOrLinkedUserId = userId;
+  if (userId !== null) {
+    try {
+      if (authDb !== null) {
+        await authDb.users.patch(userId, userData);
+      } else {
+        await ctx.db.patch(userId, userData);
+      }
+    } catch (error) {
+      throw new Error(
+        `Could not update user document with ID \`${userId}\`, ` +
+          `either the user has been deleted but their account has not, ` +
+          `or the profile data doesn't match the \`users\` table schema: ` +
+          `${(error as Error).message}`,
+      );
+    }
+  } else {
+    userId =
+      authDb !== null
+        ? ((await authDb.users.insert(userData)) as GenericId<"user">)
+        : await ctx.db.insert("user", userData);
+  }
+  const afterUserCreatedOrUpdated = config.callbacks?.afterUserCreatedOrUpdated;
+  if (afterUserCreatedOrUpdated !== undefined) {
+    logWithLevel(
+      LOG_LEVELS.DEBUG,
+      "Calling custom afterUserCreatedOrUpdated callback",
+    );
+    await afterUserCreatedOrUpdated(ctx, {
+      userId,
+      existingUserId: existingOrLinkedUserId,
+      ...args,
+    });
+  } else {
+    logWithLevel(
+      LOG_LEVELS.DEBUG,
+      "No custom afterUserCreatedOrUpdated callback, skipping",
+    );
+  }
+  return userId;
+}
+
+async function uniqueUserWithVerifiedEmail(
+  ctx: MutationCtx,
+  email: string,
+  config: ConvexAuthConfig,
+) {
+  if (config.component !== undefined) {
+    const authDb = createAuthDb(ctx, config.component);
+    return (await authDb.users.findByVerifiedEmail(email)) as Doc<"user"> | null;
+  }
+  const users = await ctx.db
+    .query("user")
+    .withIndex("email", (q) => q.eq("email", email))
+    .filter((q) => q.neq(q.field("emailVerificationTime"), undefined))
+    .take(2);
+  return users.length === 1 ? users[0] : null;
+}
+
+async function uniqueUserWithVerifiedPhone(
+  ctx: MutationCtx,
+  phone: string,
+  config: ConvexAuthConfig,
+) {
+  if (config.component !== undefined) {
+    const authDb = createAuthDb(ctx, config.component);
+    return (await authDb.users.findByVerifiedPhone(phone)) as Doc<"user"> | null;
+  }
+  const users = await ctx.db
+    .query("user")
+    .withIndex("phone", (q) => q.eq("phone", phone))
+    .filter((q) => q.neq(q.field("phoneVerificationTime"), undefined))
+    .take(2);
+  return users.length === 1 ? users[0] : null;
+}
+
+async function createOrUpdateAccount(
+  ctx: MutationCtx,
+  userId: GenericId<"user">,
+  account:
+    | { existingAccount: Doc<"account"> }
+    | {
+        providerAccountId: string;
+        secret?: string;
+      },
+  args: CreateOrUpdateUserArgs,
+  config: ConvexAuthConfig,
+) {
+  const authDb =
+    config.component !== undefined ? createAuthDb(ctx, config.component) : null;
+  const accountId =
+    "existingAccount" in account
+      ? account.existingAccount._id
+      : authDb !== null
+        ? ((await authDb.accounts.create({
+            userId,
+            provider: args.provider.id,
+            providerAccountId: account.providerAccountId,
+            secret: account.secret,
+          })) as GenericId<"account">)
+        : await ctx.db.insert("account", {
+            userId,
+            provider: args.provider.id,
+            providerAccountId: account.providerAccountId,
+            secret: account.secret,
+          });
+  // This is never used with the default `createOrUpdateUser` implementation,
+  // but it is used for manual linking via custom `createOrUpdateUser`:
+  if (
+    "existingAccount" in account &&
+    account.existingAccount.userId !== userId
+  ) {
+    if (authDb !== null) {
+      await authDb.accounts.patch(accountId, { userId });
+    } else {
+      await ctx.db.patch(accountId, { userId });
+    }
+  }
+  if (args.profile.emailVerified) {
+    if (authDb !== null) {
+      await authDb.accounts.patch(accountId, { emailVerified: args.profile.email });
+    } else {
+      await ctx.db.patch(accountId, { emailVerified: args.profile.email });
+    }
+  }
+  if (args.profile.phoneVerified) {
+    if (authDb !== null) {
+      await authDb.accounts.patch(accountId, { phoneVerified: args.profile.phone });
+    } else {
+      await ctx.db.patch(accountId, { phoneVerified: args.profile.phone });
+    }
+  }
+  return accountId;
+}
+
+export async function getAccountOrThrow(
+  ctx: MutationCtx,
+  existingAccountId: GenericId<"account">,
+  config: ConvexAuthConfig,
+) {
+  const existingAccount =
+    config.component !== undefined
+      ? await createAuthDb(ctx, config.component).accounts.getById(existingAccountId)
+      : await ctx.db.get(existingAccountId);
+  if (existingAccount === null) {
+    throw new Error(
+      `Expected an account to exist for ID "${existingAccountId}"`,
+    );
+  }
+  return existingAccount;
+}

package/src/server/implementation/utils.ts

@@ -0,0 +1,91 @@
+import { sha256 as rawSha256 } from "@oslojs/crypto/sha2";
+import { encodeHexLowerCase } from "@oslojs/encoding";
+import {
+  RandomReader,
+  generateRandomString as osloGenerateRandomString,
+} from "@oslojs/crypto/random";
+
+export const TOKEN_SUB_CLAIM_DIVIDER = "|";
+export const REFRESH_TOKEN_DIVIDER = "|";
+
+export function stringToNumber(value: string | undefined) {
+  return value !== undefined ? Number(value) : undefined;
+}
+
+export async function sha256(input: string) {
+  return encodeHexLowerCase(rawSha256(new TextEncoder().encode(input)));
+}
+
+export function generateRandomString(length: number, alphabet: string) {
+  const random: RandomReader = {
+    read(bytes) {
+      crypto.getRandomValues(bytes);
+    },
+  };
+
+  return osloGenerateRandomString(random, alphabet, length);
+}
+
+export function logError(error: unknown) {
+  logWithLevel(
+    LOG_LEVELS.ERROR,
+    error instanceof Error
+      ? error.message + "\n" + error.stack?.replace("\\n", "\n")
+      : error,
+  );
+}
+
+export const LOG_LEVELS = {
+  ERROR: "ERROR",
+  WARN: "WARN",
+  INFO: "INFO",
+  DEBUG: "DEBUG",
+} as const;
+type LogLevel = keyof typeof LOG_LEVELS;
+
+export function logWithLevel(level: LogLevel, ...args: unknown[]) {
+  const configuredLogLevel =
+    LOG_LEVELS[
+      (process.env.AUTH_LOG_LEVEL as LogLevel | undefined) ?? "INFO"
+    ] ?? "INFO";
+  switch (level) {
+    case "ERROR":
+      console.error(...args);
+      break;
+    case "WARN":
+      if (configuredLogLevel !== "ERROR") {
+        console.warn(...args);
+      }
+      break;
+    case "INFO":
+      if (configuredLogLevel === "INFO" || configuredLogLevel === "DEBUG") {
+        console.info(...args);
+      }
+      break;
+    case "DEBUG":
+      if (configuredLogLevel === "DEBUG") {
+        console.debug(...args);
+      }
+      break;
+  }
+}
+
+const UNREDACTED_LENGTH = 5;
+export function maybeRedact(value: string) {
+  if (value === "") {
+    return "";
+  }
+  const shouldRedact = process.env.AUTH_LOG_SECRETS !== "true";
+  if (shouldRedact) {
+    if (value.length < UNREDACTED_LENGTH * 2) {
+      return "<redacted>";
+    }
+    return (
+      value.substring(0, UNREDACTED_LENGTH) +
+      "<redacted>" +
+      value.substring(value.length - UNREDACTED_LENGTH)
+    );
+  } else {
+    return value;
+  }
+}

package/src/server/index.ts

@@ -0,0 +1,74 @@
+import { parse, serialize } from "cookie";
+import { isLocalHost } from "./utils.js";
+
+export type AuthCookieConfig = {
+  maxAge: number | null;
+};
+
+export type AuthCookies = {
+  token: string | null;
+  refreshToken: string | null;
+  verifier: string | null;
+};
+
+export function authCookieNames(host?: string) {
+  const prefix = isLocalHost(host) ? "" : "__Host-";
+  return {
+    token: `${prefix}__convexAuthJWT`,
+    refreshToken: `${prefix}__convexAuthRefreshToken`,
+    verifier: `${prefix}__convexAuthOAuthVerifier`,
+  };
+}
+
+export function parseAuthCookies(
+  cookieHeader: string | null | undefined,
+  host?: string,
+): AuthCookies {
+  const names = authCookieNames(host);
+  const parsed = parse(cookieHeader ?? "");
+  return {
+    token: parsed[names.token] ?? null,
+    refreshToken: parsed[names.refreshToken] ?? null,
+    verifier: parsed[names.verifier] ?? null,
+  };
+}
+
+export function serializeAuthCookies(
+  cookies: AuthCookies,
+  host?: string,
+  config: AuthCookieConfig = { maxAge: null },
+) {
+  const names = authCookieNames(host);
+  const secure = !isLocalHost(host);
+  const base = {
+    path: "/",
+    httpOnly: true,
+    sameSite: "lax" as const,
+    secure,
+  };
+  const maxAge = config.maxAge ?? undefined;
+  return [
+    serialize(names.token, cookies.token ?? "", {
+      ...base,
+      maxAge: cookies.token === null ? 0 : maxAge,
+      expires: cookies.token === null ? new Date(0) : undefined,
+    }),
+    serialize(names.refreshToken, cookies.refreshToken ?? "", {
+      ...base,
+      maxAge: cookies.refreshToken === null ? 0 : maxAge,
+      expires: cookies.refreshToken === null ? new Date(0) : undefined,
+    }),
+    serialize(names.verifier, cookies.verifier ?? "", {
+      ...base,
+      maxAge: cookies.verifier === null ? 0 : maxAge,
+      expires: cookies.verifier === null ? new Date(0) : undefined,
+    }),
+  ];
+}
+
+export function shouldProxyAuthAction(pathname: string, apiRoute: string) {
+  if (apiRoute.endsWith("/")) {
+    return pathname === apiRoute || pathname === apiRoute.slice(0, -1);
+  }
+  return pathname === apiRoute || pathname === `${apiRoute}/`;
+}

package/src/server/oauth/NOTICE.txt

@@ -0,0 +1,21 @@
+Some code in this directory is derived from the Auth.js project
+(https://github.com/nextauthjs/next-auth), and is used according to the terms
+of that project's 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.

package/src/server/oauth/README.md

@@ -0,0 +1,7 @@
+The code in this directory is meant to handle OAuth2 and OIDC flows.
+
+The code is adapted from the @auth/core package, but since some of their types
+and functions used are internal, they're copied over but with similar structure.
+
+Everything that deviates from the original code is marked with a "ConvexAuth:"
+comment.

package/src/server/oauth/authorizationUrl.ts

@@ -0,0 +1,113 @@
+// This file corresponds to packages/core/src/lib/actions/signin/authorization-url.ts in the @auth/core package (commit 5af1f30a32e64591abc50ae4d2dba4682e525431).
+import * as checks from "./checks.js";
+import { InternalOptions } from "./types.js";
+import {
+  callbackUrl,
+  getAuthorizationSignature,
+} from "./convexAuth.js";
+import { Cookie } from "@auth/core/lib/utils/cookie.js";
+import { logWithLevel } from "../implementation/utils.js";
+
+/**
+ * Generates an authorization/request token URL.
+ *
+ * [OAuth 2](https://www.oauth.com/oauth2-servers/authorization/the-authorization-request/)
+ */
+export async function getAuthorizationUrl(
+  // ConvexAuth: we don't accept a query argument
+  options: InternalOptions<"oauth" | "oidc">,
+) {
+  const { provider } = options;
+
+  let url = provider.authorization?.url;
+
+  // ConvexAuth: ConvexAuth does slightly different logic to determine the authorization endpoint
+  const { as, authorization: authorizationEndpoint, configSource } = provider;
+
+  if (!authorizationEndpoint) {
+    throw new TypeError("Could not determine the authorization endpoint.");
+  }
+  if (!url) {
+    url = new URL(authorizationEndpoint.url);
+  }
+
+  const authParams = url.searchParams;
+
+  // ConvexAuth: The logic for the callback URL is different from Auth.js
+  const redirect_uri = callbackUrl(provider.id);
+  // TODO(ConvexAuth): Support redirect proxy URLs.
+  // If we do so, update state.create to take the data value as an origin parameter (see the Auth.js code for ref).
+  // let data: string | undefined;
+  // if (!options.isOnRedirectProxy && provider.redirectProxyUrl) {
+  //   redirect_uri = provider.redirectProxyUrl;
+  //   data = provider.callbackUrl;
+  //   logger.debug("using redirect proxy", { redirect_uri, data });
+  // }
+
+  const params = Object.assign(
+    {
+      response_type: "code",
+      // clientId can technically be undefined, should we check this in assert.ts or rely on the Authorization Server to do it?
+      client_id: provider.clientId,
+      redirect_uri,
+      // @ts-expect-error TODO:
+      ...provider.authorization?.params,
+    },
+    Object.fromEntries(url.searchParams.entries() ?? []),
+    // ConvexAuth: no query arguments are combined in the params
+  );
+
+  for (const k in params) authParams.set(k, params[k]);
+
+  const cookies: Cookie[] = [];
+
+  // ConvexAuth: no value passed for `origin` (Auth.js uses `data` from above)
+  const state = await checks.state.create(options);
+  if (state) {
+    authParams.set("state", state.value);
+    cookies.push(state.cookie);
+  }
+
+  // ConvexAuth: We need to save the value of the codeVerifier.
+  let codeVerifier: string | undefined;
+  if (provider.checks?.includes("pkce")) {
+    // ConvexAuth: we check where the config came from to help decide which branch to take here
+    if (configSource === "discovered" && !as.code_challenge_methods_supported?.includes("S256")) {
+      // We assume S256 PKCE support, if the server does not advertise that,
+      // a random `nonce` must be used for CSRF protection.
+      if (provider.type === "oidc") provider.checks = ["nonce"];
+    } else {
+      const pkce = await checks.pkce.create(options);
+      authParams.set("code_challenge", pkce.codeChallenge);
+      authParams.set("code_challenge_method", "S256");
+      cookies.push(pkce.cookie);
+      codeVerifier = pkce.codeVerifier;
+    }
+  }
+
+  const nonce = await checks.nonce.create(options);
+  if (nonce) {
+    authParams.set("nonce", nonce.value);
+    cookies.push(nonce.cookie);
+  }
+
+  // TODO: This does not work in normalizeOAuth because authorization endpoint can come from discovery
+  // Need to make normalizeOAuth async
+  if (provider.type === "oidc" && !url.searchParams.has("scope")) {
+    url.searchParams.set("scope", "openid profile email");
+  }
+
+  logWithLevel("DEBUG", "authorization url is ready", {
+    url,
+    cookies,
+    provider,
+  });
+
+  const convexAuthSignature = getAuthorizationSignature({
+    codeVerifier,
+    state: authParams.get("state") ?? undefined,
+    nonce: authParams.get("nonce") ?? undefined,
+  });
+
+  return { redirect: url.toString(), cookies, signature: convexAuthSignature };
+}