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

package/src/component/public/identity/users.ts

@@ -0,0 +1,354 @@
+import { v } from "convex/values";
+import { mutation, query } from "../../functions";
+import { vPaginated, vUserDoc } from "../../model";
+
+/**
+ * List users with optional filtering, sorting, and cursor-based pagination.
+ *
+ * Supports filtering by `email`, `phone`, `isAnonymous`, and `name`. When an
+ * `email` or `phone` filter is provided, the corresponding database index is
+ * used for efficient lookup; other filters are applied in-memory. Results are
+ * returned as a paginated response `{ items, nextCursor }` -- pass `nextCursor`
+ * back as `cursor` to fetch the next page, or receive `null` when all results
+ * have been exhausted.
+ *
+ * @param args.where - Optional filter object. Fields: `email` (exact match),
+ *   `phone` (exact match), `isAnonymous` (boolean), `name` (exact match).
+ * @param args.limit - Maximum number of users to return per page (1--100, default 50).
+ * @param args.cursor - An opaque cursor string from a previous response's `nextCursor`
+ *   to continue pagination, or `null` / omitted to start from the beginning.
+ * @param args.orderBy - The field to sort results by. One of `"_creationTime"`,
+ *   `"name"`, `"email"`, or `"phone"`. Defaults to `"_creationTime"`.
+ * @param args.order - Sort direction: `"asc"` or `"desc"` (default `"desc"`).
+ * @returns An object with `items` (array of user documents) and `nextCursor`
+ *   (`string | null`) for fetching subsequent pages.
+ *
+ * @example
+ * ```ts
+ * // Fetch the first page of non-anonymous users
+ * const page1 = await ctx.runQuery(
+ *   component.identity.users.userList,
+ *   { where: { isAnonymous: false }, limit: 20 },
+ * );
+ * console.log(page1.items);
+ *
+ * // Fetch the next page
+ * if (page1.nextCursor !== null) {
+ *   const page2 = await ctx.runQuery(
+ *     component.identity.users.userList,
+ *     { where: { isAnonymous: false }, limit: 20, cursor: page1.nextCursor },
+ *   );
+ * }
+ * ```
+ */
+export const userList = query({
+  args: {
+    where: v.optional(
+      v.object({
+        email: v.optional(v.string()),
+        phone: v.optional(v.string()),
+        isAnonymous: v.optional(v.boolean()),
+        name: v.optional(v.string()),
+      }),
+    ),
+    limit: v.optional(v.number()),
+    cursor: v.optional(v.union(v.string(), v.null())),
+    orderBy: v.optional(
+      v.union(
+        v.literal("_creationTime"),
+        v.literal("name"),
+        v.literal("email"),
+        v.literal("phone"),
+      ),
+    ),
+    order: v.optional(v.union(v.literal("asc"), v.literal("desc"))),
+  },
+  returns: vPaginated(vUserDoc),
+  handler: async (ctx, args) => {
+    const where = args.where ?? {};
+    const limit = Math.min(Math.max(args.limit ?? 50, 1), 100);
+    const order = args.order ?? "desc";
+
+    // Pick index based on where fields
+    let q;
+    if (where.email !== undefined) {
+      q = ctx.db
+        .query("User")
+        .withIndex("email", (idx) => idx.eq("email", where.email!));
+    } else if (where.phone !== undefined) {
+      q = ctx.db
+        .query("User")
+        .withIndex("phone", (idx) => idx.eq("phone", where.phone!));
+    } else {
+      q = ctx.db.query("User");
+    }
+
+    // Apply remaining filters
+    if (where.isAnonymous !== undefined) {
+      q = q.filter((f) => f.eq(f.field("isAnonymous"), where.isAnonymous!));
+    }
+    if (where.name !== undefined) {
+      q = q.filter((f) => f.eq(f.field("name"), where.name!));
+    }
+    // email/phone filters when not used as index
+    if (where.email !== undefined && where.phone !== undefined) {
+      q = q.filter((f) => f.eq(f.field("phone"), where.phone!));
+    }
+
+    q = q.order(order);
+
+    // Cursor-based pagination: skip past the cursor ID
+    const all = await q.collect();
+    let startIdx = 0;
+    if (args.cursor) {
+      const cursorIdx = all.findIndex((doc) => doc._id === args.cursor);
+      if (cursorIdx !== -1) {
+        startIdx = cursorIdx + 1;
+      }
+    }
+    const page = all.slice(startIdx, startIdx + limit + 1);
+    const hasMore = page.length > limit;
+    const items = hasMore ? page.slice(0, limit) : page;
+    const nextCursor = hasMore ? items[items.length - 1]._id : null;
+    return { items, nextCursor };
+  },
+});
+
+/**
+ * Retrieve a single user by their Convex document ID.
+ *
+ * Performs a direct point lookup on the `User` table. Returns `null` if the
+ * user has been deleted or never existed.
+ *
+ * @param args.userId - The Convex document ID (`Id<"User">`) of the user to retrieve.
+ * @returns The user document if it exists, or `null` otherwise.
+ *
+ * @example
+ * ```ts
+ * const user = await ctx.runQuery(
+ *   component.identity.users.userGetById,
+ *   { userId: session.userId },
+ * );
+ * if (user !== null) {
+ *   console.log(`Name: ${user.name}, Email: ${user.email}`);
+ * }
+ * ```
+ */
+export const userGetById = query({
+  args: { userId: v.id("User") },
+  returns: v.union(vUserDoc, v.null()),
+  handler: async (ctx, { userId }) => {
+    return await ctx.db.get("User", userId);
+  },
+});
+
+/**
+ * Find a user by their verified email address.
+ *
+ * Queries the `User` table using the `email_verified` index to locate users
+ * whose `email` matches and whose `emailVerificationTime` is set. If exactly
+ * one user is found, that document is returned. Returns `null` if no user has
+ * this email verified or if multiple users share the same verified email
+ * (an ambiguous state that should not occur in normal operation).
+ *
+ * @param args.email - The verified email address to search for (case-sensitive, exact match).
+ * @returns The matching user document if exactly one verified user is found, or `null` otherwise.
+ *
+ * @example
+ * ```ts
+ * const user = await ctx.runQuery(
+ *   component.identity.users.userFindByVerifiedEmail,
+ *   { email: "alice@example.com" },
+ * );
+ * if (user !== null) {
+ *   console.log(`Found verified user: ${user._id}`);
+ * }
+ * ```
+ */
+export const userFindByVerifiedEmail = query({
+  args: { email: v.string() },
+  returns: v.union(vUserDoc, v.null()),
+  handler: async (ctx, { email }) => {
+    const users = await ctx.db
+      .query("User")
+      .withIndex("email_verified", (q) =>
+        q.eq("email", email).gt("emailVerificationTime", undefined),
+      )
+      .take(2);
+    return users.length === 1 ? users[0] : null;
+  },
+});
+
+/**
+ * Find a user by their verified phone number.
+ *
+ * Queries the `User` table using the `phone_verified` index to locate users
+ * whose `phone` matches and whose `phoneVerificationTime` is set. If exactly
+ * one user is found, that document is returned. Returns `null` if no user has
+ * this phone verified or if multiple users share the same verified phone
+ * (an ambiguous state that should not occur in normal operation).
+ *
+ * @param args.phone - The verified phone number to search for (exact match, e.g. `"+15551234567"`).
+ * @returns The matching user document if exactly one verified user is found, or `null` otherwise.
+ *
+ * @example
+ * ```ts
+ * const user = await ctx.runQuery(
+ *   component.identity.users.userFindByVerifiedPhone,
+ *   { phone: "+15551234567" },
+ * );
+ * if (user !== null) {
+ *   console.log(`Found verified user: ${user._id}`);
+ * }
+ * ```
+ */
+export const userFindByVerifiedPhone = query({
+  args: { phone: v.string() },
+  returns: v.union(vUserDoc, v.null()),
+  handler: async (ctx, { phone }) => {
+    const users = await ctx.db
+      .query("User")
+      .withIndex("phone_verified", (q) =>
+        q.eq("phone", phone).gt("phoneVerificationTime", undefined),
+      )
+      .take(2);
+    return users.length === 1 ? users[0] : null;
+  },
+});
+
+/**
+ * Insert a new user document into the `User` table.
+ *
+ * Creates a brand-new user record. The `data` argument should conform to the
+ * User table schema (e.g. `name`, `email`, `phone`, `isAnonymous`, `image`,
+ * `extend`), but is typed as `any` to allow flexible extension.
+ *
+ * @param args.data - The user document fields to insert. Typically includes `name`,
+ *   `email`, `isAnonymous`, and any custom fields under `extend`.
+ * @returns The document ID of the newly created user.
+ *
+ * @example
+ * ```ts
+ * const userId = await ctx.runMutation(
+ *   component.identity.users.userInsert,
+ *   {
+ *     data: {
+ *       name: "Alice",
+ *       email: "alice@example.com",
+ *       isAnonymous: false,
+ *     },
+ *   },
+ * );
+ * ```
+ */
+export const userInsert = mutation({
+  args: { data: v.any() },
+  returns: v.id("User"),
+  handler: async (ctx, { data }) => {
+    return await ctx.db.insert("User", data);
+  },
+});
+
+/**
+ * Insert a new user or update an existing one (upsert).
+ *
+ * When `userId` is provided and refers to an existing user, the document is
+ * patched with the supplied `data` and the same `userId` is returned. When
+ * `userId` is omitted or `undefined`, a new user document is inserted and its
+ * generated ID is returned. This is the primary mechanism used during sign-in
+ * flows to either create or refresh user profile data.
+ *
+ * @param args.userId - The document ID of an existing user to update. If `undefined`,
+ *   a new user is created instead.
+ * @param args.data - The user document fields to insert or merge. Accepts the same
+ *   shape as the User table schema.
+ * @returns The document ID of the created or updated user.
+ *
+ * @example
+ * ```ts
+ * // Create a new user if none exists, or update the existing one
+ * const userId = await ctx.runMutation(
+ *   component.identity.users.userUpsert,
+ *   {
+ *     userId: existingUserId ?? undefined,
+ *     data: { name: "Alice", email: "alice@example.com" },
+ *   },
+ * );
+ * ```
+ */
+export const userUpsert = mutation({
+  args: { userId: v.optional(v.id("User")), data: v.any() },
+  returns: v.id("User"),
+  handler: async (ctx, { userId, data }) => {
+    if (userId !== undefined) {
+      await ctx.db.patch("User", userId, data);
+      return userId;
+    }
+    return await ctx.db.insert("User", data);
+  },
+});
+
+/**
+ * Patch an existing user document with partial data.
+ *
+ * Merges the provided fields into the existing user document. Fields not
+ * included in `data` are left unchanged. Useful for updating profile
+ * information such as `name`, `email`, or custom `extend` fields without
+ * overwriting the entire document.
+ *
+ * @param args.userId - The document ID of the user to update.
+ * @param args.data - A partial object containing the fields to merge into the user document.
+ * @returns `null` on success.
+ *
+ * @example
+ * ```ts
+ * await ctx.runMutation(
+ *   component.identity.users.userPatch,
+ *   {
+ *     userId: user._id,
+ *     data: { name: "Alice Smith", image: "https://example.com/avatar.png" },
+ *   },
+ * );
+ * ```
+ */
+export const userPatch = mutation({
+  args: { userId: v.id("User"), data: v.any() },
+  returns: v.null(),
+  handler: async (ctx, { userId, data }) => {
+    await ctx.db.patch("User", userId, data);
+    return null;
+  },
+});
+
+/**
+ * Delete a user document by ID.
+ *
+ * Removes the user from the `User` table. This is a no-op if the user does not
+ * exist (i.e. was already deleted). Callers should ensure that related resources
+ * such as accounts, sessions, and refresh tokens are cleaned up separately.
+ *
+ * @param args.userId - The document ID of the user to delete.
+ * @returns `null` on success (including when the user was already absent).
+ *
+ * @example
+ * ```ts
+ * await ctx.runMutation(
+ *   component.identity.users.userDelete,
+ *   { userId: user._id },
+ * );
+ * ```
+ */
+export const userDelete = mutation({
+  args: { userId: v.id("User") },
+  returns: v.null(),
+  handler: async (ctx, { userId }) => {
+    if ((await ctx.db.get("User", userId)) !== null) {
+      await ctx.db.delete("User", userId);
+    }
+    return null;
+  },
+});
+
+// ============================================================================
+// Accounts
+// ============================================================================

package/src/component/public/identity/verifiers.ts

@@ -0,0 +1,157 @@
+import { v } from "convex/values";
+import { mutation, query } from "../../functions";
+import { vAuthVerifierDoc } from "../../model";
+
+/**
+ * Create a new PKCE verifier, optionally linked to a session.
+ *
+ * Inserts a document into the `AuthVerifier` table. Verifiers are used during
+ * OAuth/OIDC flows to implement the PKCE (Proof Key for Code Exchange) pattern,
+ * preventing authorization code interception attacks. The verifier can optionally
+ * be linked to an existing session for session-aware flows.
+ *
+ * @param args.sessionId - An optional session document ID to associate with the verifier.
+ *   When provided, the verifier is scoped to the given session.
+ * @returns The document ID of the newly created verifier.
+ *
+ * @example
+ * ```ts
+ * const verifierId = await ctx.runMutation(
+ *   component.identity.verifiers.verifierCreate,
+ *   { sessionId: session._id },
+ * );
+ * ```
+ */
+export const verifierCreate = mutation({
+  args: { sessionId: v.optional(v.id("Session")) },
+  returns: v.id("AuthVerifier"),
+  handler: async (ctx, { sessionId }) => {
+    return await ctx.db.insert("AuthVerifier", { sessionId: sessionId as any });
+  },
+});
+
+/**
+ * Retrieve a single verifier by its Convex document ID.
+ *
+ * Performs a direct point lookup on the `AuthVerifier` table. Returns `null` if
+ * the verifier has been deleted or never existed.
+ *
+ * @param args.verifierId - The Convex document ID (`Id<"AuthVerifier">`) of the verifier to retrieve.
+ * @returns The verifier document if it exists, or `null` otherwise.
+ *
+ * @example
+ * ```ts
+ * const verifier = await ctx.runQuery(
+ *   component.identity.verifiers.verifierGetById,
+ *   { verifierId: storedVerifierId },
+ * );
+ * if (verifier !== null) {
+ *   console.log(`Verifier signature: ${verifier.signature}`);
+ * }
+ * ```
+ */
+export const verifierGetById = query({
+  args: { verifierId: v.id("AuthVerifier") },
+  returns: v.union(vAuthVerifierDoc, v.null()),
+  handler: async (ctx, { verifierId }) => {
+    return await ctx.db.get("AuthVerifier", verifierId);
+  },
+});
+
+/**
+ * Look up a verifier by its cryptographic signature.
+ *
+ * Queries the `AuthVerifier` table using the `signature` index to find the
+ * unique verifier matching the given signature string. This is the primary
+ * lookup used during the OAuth callback phase to correlate the incoming
+ * authorization response with the original PKCE challenge.
+ *
+ * @param args.signature - The cryptographic signature string to search for (exact match).
+ * @returns The matching verifier document, or `null` if no verifier has the given signature.
+ *
+ * @example
+ * ```ts
+ * const verifier = await ctx.runQuery(
+ *   component.identity.verifiers.verifierGetBySignature,
+ *   { signature: incomingStateParam },
+ * );
+ * if (verifier === null) {
+ *   throw new Error("Invalid or expired OAuth state");
+ * }
+ * ```
+ */
+export const verifierGetBySignature = query({
+  args: { signature: v.string() },
+  returns: v.union(vAuthVerifierDoc, v.null()),
+  handler: async (ctx, { signature }) => {
+    return await ctx.db
+      .query("AuthVerifier")
+      .withIndex("signature", (q) => q.eq("signature", signature))
+      .unique();
+  },
+});
+
+/**
+ * Patch a verifier document with partial data.
+ *
+ * Merges the provided fields into the existing verifier document. This is
+ * typically used to set the `signature` field after the verifier is initially
+ * created, or to associate a `sessionId` with an existing verifier.
+ *
+ * @param args.verifierId - The document ID of the verifier to update.
+ * @param args.data - A partial object containing the fields to merge into the verifier document
+ *   (e.g. `{ signature: string }` or `{ sessionId: Id<"Session"> }`).
+ * @returns `null` on success.
+ *
+ * @example
+ * ```ts
+ * // Set the PKCE signature on the verifier
+ * await ctx.runMutation(
+ *   component.identity.verifiers.verifierPatch,
+ *   {
+ *     verifierId: verifier._id,
+ *     data: { signature: generatedSignature },
+ *   },
+ * );
+ * ```
+ */
+export const verifierPatch = mutation({
+  args: { verifierId: v.id("AuthVerifier"), data: v.any() },
+  returns: v.null(),
+  handler: async (ctx, { verifierId, data }) => {
+    await ctx.db.patch("AuthVerifier", verifierId, data);
+    return null;
+  },
+});
+
+/**
+ * Delete a verifier document permanently.
+ *
+ * Removes the verifier from the `AuthVerifier` table. This is typically called
+ * after a successful OAuth callback to clean up the consumed PKCE state, or
+ * to expire stale verifiers that were never completed.
+ *
+ * @param args.verifierId - The document ID of the verifier to delete.
+ * @returns `null` on success.
+ *
+ * @example
+ * ```ts
+ * // Clean up the verifier after a successful OAuth exchange
+ * await ctx.runMutation(
+ *   component.identity.verifiers.verifierDelete,
+ *   { verifierId: verifier._id },
+ * );
+ * ```
+ */
+export const verifierDelete = mutation({
+  args: { verifierId: v.id("AuthVerifier") },
+  returns: v.null(),
+  handler: async (ctx, { verifierId }) => {
+    await ctx.db.delete("AuthVerifier", verifierId);
+    return null;
+  },
+});
+
+// ============================================================================
+// Verification Codes
+// ============================================================================