@robelest/convex-auth 0.0.4-preview.2 → 0.0.4-preview.21

package/src/server/{implementation/users.ts → users.ts}

@@ -1,9 +1,11 @@
+import { Fx } from "@robelest/fx";
 import { GenericId } from "convex/values";
+
+import { authDb } from "./db";
+import { AuthError } from "./authError";
 import { Doc, MutationCtx } from "./types";
-import { AuthProviderMaterializedConfig, ConvexAuthConfig } from "../types";
+import { AuthProviderMaterializedConfig, ConvexAuthConfig } from "./types";
 import { LOG_LEVELS, logWithLevel } from "./utils";
-import { authDb } from "./db";
-import { throwAuthError } from "../errors";
 
 type CreateOrUpdateUserArgs = {
   type: "oauth" | "credentials" | "email" | "phone" | "verification";
@@ -14,24 +16,43 @@ type CreateOrUpdateUserArgs = {
     emailVerified?: boolean;
     phoneVerified?: boolean;
   };
+  accountExtend?: Record<string, unknown>;
   shouldLinkViaEmail?: boolean;
   shouldLinkViaPhone?: boolean;
 };
 
+function mergeExtend(
+  existing: unknown,
+  incoming: Record<string, unknown> | undefined,
+) {
+  if (!incoming) {
+    return undefined;
+  }
+  const existingRecord =
+    typeof existing === "object" &&
+    existing !== null &&
+    !Array.isArray(existing)
+      ? (existing as Record<string, unknown>)
+      : undefined;
+  return existingRecord ? { ...existingRecord, ...incoming } : incoming;
+}
+
+/** @internal */
 export async function upsertUserAndAccount(
   ctx: MutationCtx,
-  sessionId: GenericId<"session"> | null,
+  sessionId: GenericId<"Session"> | null,
   account:
-    | { existingAccount: Doc<"account"> }
+    | { existingAccount: Doc<"Account"> }
     | {
         providerAccountId: string;
         secret?: string;
       },
   args: CreateOrUpdateUserArgs,
   config: ConvexAuthConfig,
+  opts?: { existingUserId?: GenericId<"User"> },
 ): Promise<{
-  userId: GenericId<"user">;
-  accountId: GenericId<"account">;
+  userId: GenericId<"User">;
+  accountId: GenericId<"Account">;
 }> {
   const userId = await defaultCreateOrUpdateUser(
     ctx,
@@ -39,17 +60,25 @@ export async function upsertUserAndAccount(
     "existingAccount" in account ? account.existingAccount : null,
     args,
     config,
+    opts?.existingUserId ?? null,
+  );
+  const accountId = await createOrUpdateAccount(
+    ctx,
+    userId,
+    account,
+    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,
+  existingSessionId: GenericId<"Session"> | null,
+  existingAccount: Doc<"Account"> | null,
   args: CreateOrUpdateUserArgs,
   config: ConvexAuthConfig,
+  existingUserIdOverride: GenericId<"User"> | null,
 ) {
   logWithLevel(LOG_LEVELS.DEBUG, "defaultCreateOrUpdateUser args:", {
     existingAccountId: existingAccount?._id,
@@ -69,6 +98,7 @@ async function defaultCreateOrUpdateUser(
   const {
     provider,
     profile: {
+      id: _profileId,
       emailVerified: profileEmailVerified,
       phoneVerified: profilePhoneVerified,
       ...profile
@@ -76,57 +106,76 @@ async function defaultCreateOrUpdateUser(
   } = args;
   const emailVerified =
     profileEmailVerified ??
-    (provider.type === "oauth" &&
-      provider.allowDangerousEmailAccountLinking !== false);
+    (provider.type === "oauth" && provider.accountLinking !== "none");
   const phoneVerified = profilePhoneVerified ?? false;
   const shouldLinkViaEmail =
     args.shouldLinkViaEmail || emailVerified || provider.type === "email";
   const shouldLinkViaPhone =
     args.shouldLinkViaPhone || phoneVerified || provider.type === "phone";
 
-  let userId = existingUserId;
+  let userId = existingUserId ?? existingUserIdOverride;
   if (existingUserId === null) {
     const existingUserWithVerifiedEmailId =
       typeof profile.email === "string" && shouldLinkViaEmail
-        ? (await uniqueUserWithVerifiedEmail(ctx, profile.email, config))?._id ??
-          null
+        ? ((await uniqueUserWithVerifiedEmail(ctx, profile.email, config))
+            ?._id ?? null)
         : null;
 
     const existingUserWithVerifiedPhoneId =
       typeof profile.phone === "string" && shouldLinkViaPhone
-        ? (await uniqueUserWithVerifiedPhone(ctx, profile.phone, config))?._id ??
-          null
+        ? ((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 linkDispatch = {
+      tag:
+        existingUserWithVerifiedEmailId !== null &&
+        existingUserWithVerifiedPhoneId !== null
+          ? "both"
+          : existingUserWithVerifiedEmailId !== null
+            ? "email"
+            : existingUserWithVerifiedPhoneId !== null
+              ? "phone"
+              : "none",
+      existingUserWithVerifiedEmailId,
+      existingUserWithVerifiedPhoneId,
+    } as const;
+
+    const linkHandlers = {
+      both: () =>
+        Fx.sync(() => {
+          logWithLevel(
+            LOG_LEVELS.DEBUG,
+            `Found existing email and phone verified users, so not linking: email: ${linkDispatch.existingUserWithVerifiedEmailId}, phone: ${linkDispatch.existingUserWithVerifiedPhoneId}`,
+          );
+          return null;
+        }),
+      email: () =>
+        Fx.sync(() => {
+          logWithLevel(
+            LOG_LEVELS.DEBUG,
+            `Found existing email verified user, linking: ${linkDispatch.existingUserWithVerifiedEmailId}`,
+          );
+          return linkDispatch.existingUserWithVerifiedEmailId;
+        }),
+      phone: () =>
+        Fx.sync(() => {
+          logWithLevel(
+            LOG_LEVELS.DEBUG,
+            `Found existing phone verified user, linking: ${linkDispatch.existingUserWithVerifiedPhoneId}`,
+          );
+          return linkDispatch.existingUserWithVerifiedPhoneId;
+        }),
+      none: () =>
+        Fx.sync(() => {
+          logWithLevel(
+            LOG_LEVELS.DEBUG,
+            "No existing verified users found, creating new user",
+          );
+          return null;
+        }),
+    } as const;
+
+    userId = await Fx.run(linkHandlers[linkDispatch.tag]());
   }
   const userData = {
     ...(emailVerified ? { emailVerificationTime: Date.now() } : null),
@@ -135,16 +184,21 @@ async function defaultCreateOrUpdateUser(
   };
   const existingOrLinkedUserId = userId;
   if (userId !== null) {
-    try {
-      await db.users.patch(userId, userData);
-    } catch (error) {
-      throwAuthError("USER_UPDATE_FAILED", `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}`);
-    }
+    await Fx.run(
+      Fx.from({
+        ok: () => db.users.patch(userId!, userData),
+        err: (error) =>
+          new AuthError(
+            "USER_UPDATE_FAILED",
+            `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}`,
+          ),
+      }).pipe(Fx.recover((e) => Fx.fatal(e.toConvexError()))),
+    );
   } else {
-    userId = (await db.users.insert(userData)) as GenericId<"user">;
+    userId = (await db.users.insert(userData)) as GenericId<"User">;
   }
   const afterUserCreatedOrUpdated = config.callbacks?.afterUserCreatedOrUpdated;
   if (afterUserCreatedOrUpdated !== undefined) {
@@ -172,7 +226,7 @@ async function uniqueUserWithVerifiedEmail(
   config: ConvexAuthConfig,
 ) {
   const db = authDb(ctx, config);
-  return (await db.users.findByVerifiedEmail(email)) as Doc<"user"> | null;
+  return (await db.users.findByVerifiedEmail(email)) as Doc<"User"> | null;
 }
 
 async function uniqueUserWithVerifiedPhone(
@@ -181,14 +235,14 @@ async function uniqueUserWithVerifiedPhone(
   config: ConvexAuthConfig,
 ) {
   const db = authDb(ctx, config);
-  return (await db.users.findByVerifiedPhone(phone)) as Doc<"user"> | null;
+  return (await db.users.findByVerifiedPhone(phone)) as Doc<"User"> | null;
 }
 
 async function createOrUpdateAccount(
   ctx: MutationCtx,
-  userId: GenericId<"user">,
+  userId: GenericId<"User">,
   account:
-    | { existingAccount: Doc<"account"> }
+    | { existingAccount: Doc<"Account"> }
     | {
         providerAccountId: string;
         secret?: string;
@@ -197,6 +251,10 @@ async function createOrUpdateAccount(
   config: ConvexAuthConfig,
 ) {
   const db = authDb(ctx, config);
+  const mergedExtend =
+    "existingAccount" in account
+      ? mergeExtend(account.existingAccount.extend, args.accountExtend)
+      : args.accountExtend;
   const accountId =
     "existingAccount" in account
       ? account.existingAccount._id
@@ -205,7 +263,8 @@ async function createOrUpdateAccount(
           provider: args.provider.id,
           providerAccountId: account.providerAccountId,
           secret: account.secret,
-        })) as GenericId<"account">);
+          extend: mergedExtend,
+        })) as GenericId<"Account">);
   // This is never used with the default `createOrUpdateUser` implementation,
   // but it is used for manual linking via custom `createOrUpdateUser`:
   if (
@@ -214,23 +273,18 @@ async function createOrUpdateAccount(
   ) {
     await db.accounts.patch(accountId, { userId });
   }
+  const accountPatchData: Record<string, unknown> = {};
+  if (mergedExtend) {
+    accountPatchData.extend = mergedExtend;
+  }
   if (args.profile.emailVerified) {
-    await db.accounts.patch(accountId, { emailVerified: args.profile.email });
+    accountPatchData.emailVerified = args.profile.email;
   }
   if (args.profile.phoneVerified) {
-    await db.accounts.patch(accountId, { phoneVerified: args.profile.phone });
+    accountPatchData.phoneVerified = args.profile.phone;
   }
-  return accountId;
-}
-
-export async function getAccountOrThrow(
-  ctx: MutationCtx,
-  existingAccountId: GenericId<"account">,
-  config: ConvexAuthConfig,
-) {
-  const existingAccount = await authDb(ctx, config).accounts.getById(existingAccountId);
-  if (existingAccount === null) {
-    throwAuthError("ACCOUNT_NOT_FOUND", `Expected an account to exist for ID "${existingAccountId}"`);
+  if (Object.keys(accountPatchData).length > 0) {
+    await db.accounts.patch(accountId, accountPatchData);
   }
-  return existingAccount;
+  return accountId;
 }

package/src/server/utils.ts

@@ -1,14 +1,201 @@
-import { throwAuthError } from "./errors";
+import {
+  RandomReader,
+  generateRandomString as osloGenerateRandomString,
+} from "@oslojs/crypto/random";
+import { sha256 as rawSha256 } from "@oslojs/crypto/sha2";
+import {
+  decodeBase64urlIgnorePadding,
+  encodeBase64urlNoPadding,
+  encodeHexLowerCase,
+} from "@oslojs/encoding";
 
+import { AuthError } from "./authError";
+
+/**
+ * Require an environment variable to be set, throwing at config time if missing.
+ *
+ * Uses `AuthError.toConvexError()` directly since this is a synchronous guard
+ * called inline in many expressions — not suitable for Fx pipeline wrapping.
+ */
+/** @internal */
 export function requireEnv(name: string) {
   const value = process.env[name];
   if (value === undefined) {
-    throwAuthError("MISSING_ENV_VAR", `Missing environment variable \`${name}\``, { variable: name });
+    throw new AuthError(
+      "MISSING_ENV_VAR",
+      `Missing environment variable \`${name}\``,
+      { variable: name },
+    ).toConvexError();
   }
   return value;
 }
 
+/** @internal */
 export function isLocalHost(host?: string) {
-  return /(localhost|127\.0\.0\.1):\d+/.test(
-  host ?? "");
-}
+  if (host === undefined) {
+    return false;
+  }
+  const raw = host.includes("://") ? host : `http://${host}`;
+  let url: URL;
+  try {
+    url = new URL(raw);
+  } catch {
+    return false;
+  }
+  return (
+    url.hostname === "localhost" ||
+    url.hostname === "127.0.0.1" ||
+    url.hostname === "::1"
+  );
+}
+
+// Internal server utilities (merged from former internalUtils.ts)
+
+/** @internal */
+export const TOKEN_SUB_CLAIM_DIVIDER = "|";
+/** @internal */
+export const REFRESH_TOKEN_DIVIDER = "|";
+
+/** @internal */
+export async function sha256(input: string) {
+  return encodeHexLowerCase(rawSha256(new TextEncoder().encode(input)));
+}
+
+/** @internal */
+export function generateRandomString(length: number, alphabet: string) {
+  const random: RandomReader = {
+    read(bytes) {
+      crypto.getRandomValues(bytes as Uint8Array<ArrayBuffer>);
+    },
+  };
+
+  return osloGenerateRandomString(random, alphabet, length);
+}
+
+/** @internal */
+export function errorMessage(error: unknown) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/** @internal */
+export function logError(error: unknown) {
+  logWithLevel(
+    LOG_LEVELS.ERROR,
+    error instanceof Error
+      ? error.message + "\n" + error.stack?.replace("\\n", "\n")
+      : error,
+  );
+}
+
+/** @internal */
+export const LOG_LEVELS = {
+  ERROR: "ERROR",
+  WARN: "WARN",
+  INFO: "INFO",
+  DEBUG: "DEBUG",
+} as const;
+type LogLevel = keyof typeof LOG_LEVELS;
+
+/** @internal */
+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;
+/** @internal */
+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;
+  }
+}
+
+const SECRET_KEY_ENV = "AUTH_SECRET_ENCRYPTION_KEY";
+const SECRET_IV_LENGTH = 12;
+
+function toArrayBuffer(bytes: Uint8Array) {
+  return bytes.buffer.slice(
+    bytes.byteOffset,
+    bytes.byteOffset + bytes.byteLength,
+  ) as ArrayBuffer;
+}
+
+async function getSecretCryptoKey() {
+  const material = requireEnv(SECRET_KEY_ENV);
+  const rawKey = rawSha256(new TextEncoder().encode(material));
+  return await crypto.subtle.importKey(
+    "raw",
+    toArrayBuffer(rawKey),
+    { name: "AES-GCM" },
+    false,
+    ["encrypt", "decrypt"],
+  );
+}
+
+/** @internal */
+export async function encryptSecret(value: string) {
+  const key = await getSecretCryptoKey();
+  const iv = crypto.getRandomValues(new Uint8Array(SECRET_IV_LENGTH));
+  const encrypted = await crypto.subtle.encrypt(
+    { name: "AES-GCM", iv: toArrayBuffer(iv) },
+    key,
+    toArrayBuffer(new TextEncoder().encode(value)),
+  );
+  return `${encodeBase64urlNoPadding(iv)}.${encodeBase64urlNoPadding(new Uint8Array(encrypted))}`;
+}
+
+/** @internal */
+export async function decryptSecret(ciphertext: string) {
+  const [ivEncoded, payloadEncoded] = ciphertext.split(".");
+  if (!ivEncoded || !payloadEncoded) {
+    throw new AuthError(
+      "INVALID_PARAMETERS",
+      "Stored enterprise secret is malformed.",
+    ).toConvexError();
+  }
+  const key = await getSecretCryptoKey();
+  const decrypted = await crypto.subtle.decrypt(
+    {
+      name: "AES-GCM",
+      iv: toArrayBuffer(decodeBase64urlIgnorePadding(ivEncoded)),
+    },
+    key,
+    toArrayBuffer(decodeBase64urlIgnorePadding(payloadEncoded)),
+  );
+  return new TextDecoder().decode(decrypted);
+}

package/src/test.ts

@@ -1,15 +1,33 @@
-import type { GenericSchema, SchemaDefinition } from "convex/server";
 import type { TestConvex } from "convex-test";
+import type { GenericSchema, SchemaDefinition } from "convex/server";
+
 import schema from "./component/schema";
 
 type ImportMetaWithGlob = ImportMeta & {
   glob: (pattern: string) => Record<string, () => Promise<unknown>>;
 };
 
-const modules = (import.meta as ImportMetaWithGlob).glob(
-  "./component/**/*.ts",
-);
+const modules = (import.meta as ImportMetaWithGlob).glob("./component/**/*.ts");
 
+/**
+ * Register the Convex Auth component in a `convex-test` environment.
+ *
+ * Use this in tests to mount the bundled auth component under a chosen
+ * component name before invoking its functions.
+ *
+ * @param t - The `convex-test` test harness.
+ * @param name - Component mount name. Defaults to `"auth"`.
+ * @returns Nothing.
+ *
+ * @example
+ * ```ts
+ * import { convexTest } from "convex-test";
+ * import { register } from "@robelest/convex-auth/test";
+ *
+ * const t = convexTest(schema);
+ * register(t);
+ * ```
+ */
 export function register(
   t: TestConvex<SchemaDefinition<GenericSchema, boolean>>,
   name: string = "auth",
@@ -17,6 +35,12 @@ export function register(
   t.registerComponent(name, schema, modules);
 }
 
+/**
+ * Test helpers bundled for `convex-test` setups.
+ *
+ * Exposes the auth component `schema`, lazily discovered `modules`, and the
+ * `register()` helper as a convenience default export.
+ */
 export default {
   register,
   schema,