@robelest/convex-auth 0.0.4-preview.25 → 0.0.4-preview.28

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

@@ -1,149 +0,0 @@
-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

@@ -1,210 +0,0 @@
-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

@@ -1,251 +0,0 @@
-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();
-  },
-});