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

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

@@ -0,0 +1,148 @@
+import { v } from "convex/values";
+import { mutation, query } from "../../functions";
+import { vVerificationCodeDoc } from "../../model";
+
+/**
+ * Find a verification code by its associated account ID.
+ *
+ * Queries the `VerificationCode` table using the `account_id` index to locate
+ * the unique verification code linked to the given account. Each account has at
+ * most one active verification code at a time.
+ *
+ * @param args.accountId - The document ID of the account whose verification code should be retrieved.
+ * @returns The verification code document if one exists for the account, or `null` otherwise.
+ *
+ * @example
+ * ```ts
+ * const code = await ctx.runQuery(
+ *   component.identity.codes.verificationCodeGetByAccountId,
+ *   { accountId: account._id },
+ * );
+ * if (code !== null && code.expirationTime > Date.now()) {
+ *   console.log("Active verification code exists");
+ * }
+ * ```
+ */
+export const verificationCodeGetByAccountId = query({
+  args: { accountId: v.id("Account") },
+  returns: v.union(vVerificationCodeDoc, v.null()),
+  handler: async (ctx, { accountId }) => {
+    return await ctx.db
+      .query("VerificationCode")
+      .withIndex("account_id", (q) => q.eq("accountId", accountId as any))
+      .unique();
+  },
+});
+
+/**
+ * Find a verification code by its code string value.
+ *
+ * Queries the `VerificationCode` table using the `code` index to locate the
+ * unique verification code document matching the given code string. This is
+ * the primary lookup used when a user submits an OTP or clicks a magic link.
+ *
+ * @param args.code - The verification code string to look up (e.g. a 6-digit OTP or a magic-link token).
+ * @returns The verification code document if a match is found, or `null` otherwise.
+ *
+ * @example
+ * ```ts
+ * const codeDoc = await ctx.runQuery(
+ *   component.identity.codes.verificationCodeGetByCode,
+ *   { code: "482910" },
+ * );
+ * if (codeDoc !== null && codeDoc.expirationTime > Date.now()) {
+ *   console.log(`Code is valid for account: ${codeDoc.accountId}`);
+ * }
+ * ```
+ */
+export const verificationCodeGetByCode = query({
+  args: { code: v.string() },
+  returns: v.union(vVerificationCodeDoc, v.null()),
+  handler: async (ctx, { code }) => {
+    return await ctx.db
+      .query("VerificationCode")
+      .withIndex("code", (q) => q.eq("code", code))
+      .unique();
+  },
+});
+
+/**
+ * Create a new verification code for OTP, magic link, or OAuth flows.
+ *
+ * Inserts a document into the `VerificationCode` table that ties a short-lived
+ * code to a specific account and provider. The code can be used for email OTP,
+ * phone OTP, magic link, or OAuth state verification depending on the flow.
+ *
+ * @param args.accountId - The document ID of the account this verification code is associated with.
+ * @param args.provider - The name of the authentication provider initiating the verification
+ *   (e.g. `"resend-otp"`, `"twilio-otp"`, `"google"`).
+ * @param args.code - The verification code string (e.g. a random OTP or an opaque token for magic links).
+ * @param args.expirationTime - The Unix timestamp (in milliseconds) at which this code expires.
+ * @param args.verifier - An optional PKCE verifier string used in OAuth/OIDC flows to prevent CSRF attacks.
+ * @param args.emailVerified - An optional email address that will be marked as verified upon successful
+ *   code redemption.
+ * @param args.phoneVerified - An optional phone number that will be marked as verified upon successful
+ *   code redemption.
+ * @returns The document ID of the newly created verification code.
+ *
+ * @example
+ * ```ts
+ * const codeId = await ctx.runMutation(
+ *   component.identity.codes.verificationCodeCreate,
+ *   {
+ *     accountId: account._id,
+ *     provider: "resend-otp",
+ *     code: "482910",
+ *     expirationTime: Date.now() + 10 * 60 * 1000, // 10 minutes
+ *     emailVerified: "alice@example.com",
+ *   },
+ * );
+ * ```
+ */
+export const verificationCodeCreate = mutation({
+  args: {
+    accountId: v.id("Account"),
+    provider: v.string(),
+    code: v.string(),
+    expirationTime: v.number(),
+    verifier: v.optional(v.string()),
+    emailVerified: v.optional(v.string()),
+    phoneVerified: v.optional(v.string()),
+  },
+  returns: v.id("VerificationCode"),
+  handler: async (ctx, args) => {
+    return await ctx.db.insert("VerificationCode", args as any);
+  },
+});
+
+/**
+ * Delete a verification code document permanently.
+ *
+ * Removes the verification code from the `VerificationCode` table. This is
+ * typically called after the code has been successfully redeemed or when it
+ * needs to be invalidated (e.g. replaced by a new code).
+ *
+ * @param args.verificationCodeId - The document ID of the verification code to delete.
+ * @returns `null` on success.
+ *
+ * @example
+ * ```ts
+ * // Delete the code after successful verification
+ * await ctx.runMutation(
+ *   component.identity.codes.verificationCodeDelete,
+ *   { verificationCodeId: codeDoc._id },
+ * );
+ * ```
+ */
+export const verificationCodeDelete = mutation({
+  args: { verificationCodeId: v.id("VerificationCode") },
+  returns: v.null(),
+  handler: async (ctx, { verificationCodeId }) => {
+    await ctx.db.delete("VerificationCode", verificationCodeId);
+    return null;
+  },
+});
+
+// ============================================================================
+// Refresh Tokens
+// ============================================================================

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

@@ -0,0 +1,209 @@
+import { v } from "convex/values";
+import { mutation, query } from "../../functions";
+import { vPaginated, vSessionDoc } from "../../model";
+
+/**
+ * List sessions with optional filtering and cursor-based pagination.
+ *
+ * Supports filtering by `userId` to retrieve only sessions belonging to a
+ * specific user. When a `userId` filter is provided, the `user_id` index is
+ * used for efficient lookup. 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. Currently supports `userId` to
+ *   restrict results to sessions for a specific user.
+ * @param args.limit - Maximum number of sessions 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.order - Sort direction: `"asc"` or `"desc"` (default `"desc"`).
+ * @returns An object with `items` (array of session documents) and `nextCursor`
+ *   (`string | null`) for fetching subsequent pages.
+ *
+ * @example
+ * ```ts
+ * // List the 10 most recent sessions for a user
+ * const page = await ctx.runQuery(
+ *   component.identity.sessions.sessionList,
+ *   { where: { userId: user._id }, limit: 10, order: "desc" },
+ * );
+ * for (const session of page.items) {
+ *   console.log(`Session ${session._id} expires at ${session.expirationTime}`);
+ * }
+ * ```
+ */
+export const sessionList = query({
+  args: {
+    where: v.optional(
+      v.object({
+        userId: v.optional(v.id("User")),
+      }),
+    ),
+    limit: v.optional(v.number()),
+    cursor: v.optional(v.union(v.string(), v.null())),
+    order: v.optional(v.union(v.literal("asc"), v.literal("desc"))),
+  },
+  returns: vPaginated(vSessionDoc),
+  handler: async (ctx, args) => {
+    const where = args.where ?? {};
+    const limit = Math.min(Math.max(args.limit ?? 50, 1), 100);
+    const order = args.order ?? "desc";
+
+    let q;
+    if (where.userId !== undefined) {
+      q = ctx.db
+        .query("Session")
+        .withIndex("user_id", (idx) => idx.eq("userId", where.userId!));
+    } else {
+      q = ctx.db.query("Session");
+    }
+
+    q = q.order(order);
+
+    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 };
+  },
+});
+
+/**
+ * Create a new session for a user with a specified expiration time.
+ *
+ * Inserts a new document into the `Session` table, linking it to the given user.
+ * The session represents an active authenticated context and is typically created
+ * after a successful sign-in or token refresh.
+ *
+ * @param args.userId - The document ID of the user this session belongs to.
+ * @param args.expirationTime - The Unix timestamp (in milliseconds) at which this session expires.
+ * @returns The document ID of the newly created session.
+ *
+ * @example
+ * ```ts
+ * const sessionId = await ctx.runMutation(
+ *   component.identity.sessions.sessionCreate,
+ *   {
+ *     userId: user._id,
+ *     expirationTime: Date.now() + 30 * 24 * 60 * 60 * 1000, // 30 days
+ *   },
+ * );
+ * ```
+ */
+export const sessionCreate = mutation({
+  args: { userId: v.id("User"), expirationTime: v.number() },
+  returns: v.id("Session"),
+  handler: async (ctx, { userId, expirationTime }) => {
+    return await ctx.db.insert("Session", {
+      userId: userId as any,
+      expirationTime,
+    });
+  },
+});
+
+/**
+ * Retrieve a single session by its Convex document ID.
+ *
+ * Performs a direct point lookup on the `Session` table. Returns `null` if the
+ * session has been deleted or never existed. This does not check whether the
+ * session has expired -- callers should compare `expirationTime` to the current
+ * time if needed.
+ *
+ * @param args.sessionId - The Convex document ID (`Id<"Session">`) of the session to retrieve.
+ * @returns The session document if it exists, or `null` otherwise.
+ *
+ * @example
+ * ```ts
+ * const session = await ctx.runQuery(
+ *   component.identity.sessions.sessionGetById,
+ *   { sessionId: refreshToken.sessionId },
+ * );
+ * if (session !== null && session.expirationTime > Date.now()) {
+ *   console.log("Session is still active");
+ * }
+ * ```
+ */
+export const sessionGetById = query({
+  args: { sessionId: v.id("Session") },
+  returns: v.union(vSessionDoc, v.null()),
+  handler: async (ctx, { sessionId }) => {
+    return await ctx.db.get("Session", sessionId);
+  },
+});
+
+/**
+ * Delete a session document.
+ *
+ * Removes the session from the `Session` table. This is a no-op if the session
+ * does not exist (i.e. was already deleted). Callers should also clean up
+ * related refresh tokens via `refreshTokenDeleteAll` to fully invalidate the
+ * session.
+ *
+ * @param args.sessionId - The document ID of the session to delete.
+ * @returns `null` on success (including when the session was already absent).
+ *
+ * @example
+ * ```ts
+ * // Revoke a session and its tokens
+ * await ctx.runMutation(
+ *   component.identity.sessions.sessionDelete,
+ *   { sessionId: session._id },
+ * );
+ * await ctx.runMutation(
+ *   component.identity.tokens.refreshTokenDeleteAll,
+ *   { sessionId: session._id },
+ * );
+ * ```
+ */
+export const sessionDelete = mutation({
+  args: { sessionId: v.id("Session") },
+  returns: v.null(),
+  handler: async (ctx, { sessionId }) => {
+    if ((await ctx.db.get("Session", sessionId)) !== null) {
+      await ctx.db.delete("Session", sessionId);
+    }
+    return null;
+  },
+});
+
+/**
+ * List all sessions belonging to a specific user.
+ *
+ * Queries the `Session` table using the `user_id` index to efficiently retrieve
+ * every session document for the given user. Unlike `sessionList`, this returns
+ * all matching sessions without pagination.
+ *
+ * @param args.userId - The document ID of the user whose sessions should be retrieved.
+ * @returns An array of session documents for the specified user.
+ *
+ * @example
+ * ```ts
+ * const sessions = await ctx.runQuery(
+ *   component.identity.sessions.sessionListByUser,
+ *   { userId: user._id },
+ * );
+ * console.log(`User has ${sessions.length} active session(s)`);
+ * ```
+ */
+export const sessionListByUser = query({
+  args: { userId: v.id("User") },
+  returns: v.array(vSessionDoc),
+  handler: async (ctx, { userId }) => {
+    return await ctx.db
+      .query("Session")
+      .withIndex("user_id", (q) => q.eq("userId", userId as any))
+      .collect();
+  },
+});
+
+// ============================================================================
+// Verifiers
+// ============================================================================

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

@@ -0,0 +1,250 @@
+import { v } from "convex/values";
+import { mutation, query } from "../../functions";
+import { vRefreshTokenDoc } from "../../model";
+
+/**
+ * Create a new refresh token for a session.
+ *
+ * Inserts a document into the `RefreshToken` table. Refresh tokens are used to
+ * obtain new access tokens without requiring the user to re-authenticate. When
+ * a refresh token is rotated, the new token references the old one via
+ * `parentRefreshTokenId` to form a token chain for replay detection.
+ *
+ * @param args.sessionId - The document ID of the session this refresh token belongs to.
+ * @param args.expirationTime - The Unix timestamp (in milliseconds) at which this refresh token expires.
+ * @param args.parentRefreshTokenId - The document ID of the parent refresh token that was
+ *   exchanged to create this one. Omitted for the initial token in a session.
+ * @returns The document ID of the newly created refresh token.
+ *
+ * @example
+ * ```ts
+ * const tokenId = await ctx.runMutation(
+ *   component.identity.tokens.refreshTokenCreate,
+ *   {
+ *     sessionId: session._id,
+ *     expirationTime: Date.now() + 7 * 24 * 60 * 60 * 1000, // 7 days
+ *   },
+ * );
+ * ```
+ */
+export const refreshTokenCreate = mutation({
+  args: {
+    sessionId: v.id("Session"),
+    expirationTime: v.number(),
+    parentRefreshTokenId: v.optional(v.id("RefreshToken")),
+  },
+  returns: v.id("RefreshToken"),
+  handler: async (ctx, args) => {
+    return await ctx.db.insert("RefreshToken", args as any);
+  },
+});
+
+/**
+ * Retrieve a single refresh token by its Convex document ID.
+ *
+ * Performs a direct point lookup on the `RefreshToken` table. Returns `null` if
+ * the token has been deleted or never existed.
+ *
+ * @param args.refreshTokenId - The Convex document ID (`Id<"RefreshToken">`) of the token to retrieve.
+ * @returns The refresh token document if it exists, or `null` otherwise.
+ *
+ * @example
+ * ```ts
+ * const token = await ctx.runQuery(
+ *   component.identity.tokens.refreshTokenGetById,
+ *   { refreshTokenId: storedTokenId },
+ * );
+ * if (token !== null && token.expirationTime > Date.now()) {
+ *   console.log("Refresh token is still valid");
+ * }
+ * ```
+ */
+export const refreshTokenGetById = query({
+  args: { refreshTokenId: v.id("RefreshToken") },
+  returns: v.union(vRefreshTokenDoc, v.null()),
+  handler: async (ctx, { refreshTokenId }) => {
+    return await ctx.db.get("RefreshToken", refreshTokenId);
+  },
+});
+
+/**
+ * Patch a refresh token document with partial data.
+ *
+ * Merges the provided fields into the existing refresh token document. This is
+ * primarily used to record `firstUsedTime` when a refresh token is first
+ * exchanged, marking it as consumed for replay detection.
+ *
+ * @param args.refreshTokenId - The document ID of the refresh token to update.
+ * @param args.data - A partial object containing the fields to merge (e.g. `{ firstUsedTime: number }`).
+ * @returns `null` on success.
+ *
+ * @example
+ * ```ts
+ * // Mark the refresh token as used
+ * await ctx.runMutation(
+ *   component.identity.tokens.refreshTokenPatch,
+ *   {
+ *     refreshTokenId: token._id,
+ *     data: { firstUsedTime: Date.now() },
+ *   },
+ * );
+ * ```
+ */
+export const refreshTokenPatch = mutation({
+  args: { refreshTokenId: v.id("RefreshToken"), data: v.any() },
+  returns: v.null(),
+  handler: async (ctx, { refreshTokenId, data }) => {
+    await ctx.db.patch("RefreshToken", refreshTokenId, data);
+    return null;
+  },
+});
+
+/**
+ * Get child tokens that were created by exchanging a specific parent token.
+ *
+ * Queries the `RefreshToken` table using the `session_id_parent_refresh_token_id`
+ * index to find all tokens whose `parentRefreshTokenId` matches the provided
+ * parent. This is used for replay detection: if a parent token has more than
+ * one child, it indicates a potential token reuse attack.
+ *
+ * @param args.sessionId - The document ID of the session the tokens belong to.
+ * @param args.parentRefreshTokenId - The document ID of the parent refresh token whose children to retrieve.
+ * @returns An array of refresh token documents that were derived from the specified parent token.
+ *
+ * @example
+ * ```ts
+ * const children = await ctx.runQuery(
+ *   component.identity.tokens.refreshTokenGetChildren,
+ *   {
+ *     sessionId: session._id,
+ *     parentRefreshTokenId: parentToken._id,
+ *   },
+ * );
+ * if (children.length > 1) {
+ *   console.warn("Possible token reuse detected!");
+ * }
+ * ```
+ */
+export const refreshTokenGetChildren = query({
+  args: {
+    sessionId: v.id("Session"),
+    parentRefreshTokenId: v.id("RefreshToken"),
+  },
+  returns: v.array(vRefreshTokenDoc),
+  handler: async (ctx, { sessionId, parentRefreshTokenId }) => {
+    return await ctx.db
+      .query("RefreshToken")
+      .withIndex("session_id_parent_refresh_token_id", (q) =>
+        q
+          .eq("sessionId", sessionId as any)
+          .eq("parentRefreshTokenId", parentRefreshTokenId as any),
+      )
+      .collect();
+  },
+});
+
+/**
+ * List all refresh tokens belonging to a specific session.
+ *
+ * Queries the `RefreshToken` table using the `session_id_parent_refresh_token_id`
+ * index to efficiently retrieve every refresh token associated with the given
+ * session, including both active and consumed tokens.
+ *
+ * @param args.sessionId - The document ID of the session whose refresh tokens should be retrieved.
+ * @returns An array of all refresh token documents for the specified session.
+ *
+ * @example
+ * ```ts
+ * const tokens = await ctx.runQuery(
+ *   component.identity.tokens.refreshTokenListBySession,
+ *   { sessionId: session._id },
+ * );
+ * console.log(`Session has ${tokens.length} refresh token(s)`);
+ * ```
+ */
+export const refreshTokenListBySession = query({
+  args: { sessionId: v.id("Session") },
+  returns: v.array(vRefreshTokenDoc),
+  handler: async (ctx, { sessionId }) => {
+    return await ctx.db
+      .query("RefreshToken")
+      .withIndex("session_id_parent_refresh_token_id", (q) =>
+        q.eq("sessionId", sessionId as any),
+      )
+      .collect();
+  },
+});
+
+/**
+ * Delete all refresh tokens for a session.
+ *
+ * Queries the `RefreshToken` table for all tokens belonging to the given session
+ * and deletes them in parallel. This is typically called when a session is
+ * revoked or when token reuse is detected, effectively invalidating the entire
+ * token chain for that session.
+ *
+ * @param args.sessionId - The document ID of the session whose refresh tokens should be deleted.
+ * @returns `null` on success.
+ *
+ * @example
+ * ```ts
+ * // Invalidate all tokens for a compromised session
+ * await ctx.runMutation(
+ *   component.identity.tokens.refreshTokenDeleteAll,
+ *   { sessionId: session._id },
+ * );
+ * ```
+ */
+export const refreshTokenDeleteAll = mutation({
+  args: { sessionId: v.id("Session") },
+  returns: v.null(),
+  handler: async (ctx, { sessionId }) => {
+    const tokens = await ctx.db
+      .query("RefreshToken")
+      .withIndex("session_id_parent_refresh_token_id", (q) =>
+        q.eq("sessionId", sessionId as any),
+      )
+      .collect();
+    await Promise.all(
+      tokens.map((token) => ctx.db.delete("RefreshToken", token._id)),
+    );
+    return null;
+  },
+});
+
+/**
+ * Get the active (unused) refresh token for a session.
+ *
+ * Queries the `RefreshToken` table using the `session_id_first_used` index to
+ * find the most recently created token for the session that has not yet been
+ * exchanged (i.e. `firstUsedTime` is `undefined`). This represents the current
+ * valid refresh token the client should be holding.
+ *
+ * @param args.sessionId - The document ID of the session whose active refresh token should be retrieved.
+ * @returns The most recent unused refresh token document, or `null` if no active token exists
+ *   (e.g. all tokens have been consumed or the session has no tokens).
+ *
+ * @example
+ * ```ts
+ * const activeToken = await ctx.runQuery(
+ *   component.identity.tokens.refreshTokenGetActive,
+ *   { sessionId: session._id },
+ * );
+ * if (activeToken !== null) {
+ *   console.log(`Active token expires at: ${activeToken.expirationTime}`);
+ * }
+ * ```
+ */
+export const refreshTokenGetActive = query({
+  args: { sessionId: v.id("Session") },
+  returns: v.union(vRefreshTokenDoc, v.null()),
+  handler: async (ctx, { sessionId }) => {
+    return await ctx.db
+      .query("RefreshToken")
+      .withIndex("session_id_first_used", (q) =>
+        q.eq("sessionId", sessionId as any).eq("firstUsedTime", undefined),
+      )
+      .order("desc")
+      .first();
+  },
+});