@robelest/convex-auth 0.0.4-preview.32 → 0.0.4-preview.34

package/dist/component/public/identity/users.js

@@ -1,4 +1,4 @@
-import { vPaginated, vUserDoc } from "../../model.js";
+import { vPaginated, vUserDoc, vUserEmailDoc, vUserEmailSource } from "../../model.js";
 import { mutation, query } from "../../functions.js";
 import { ConvexError, v } from "convex/values";
 
@@ -24,23 +24,6 @@ import { ConvexError, v } from "convex/values";
 * @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 },
-*   );
-* }
-* ```
 */
 const userList = query({
 	args: {
@@ -84,131 +67,6 @@ const userList = query({
 	}
 });
 /**
-* 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}`);
-* }
-* ```
-*/
-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);
-	}
-});
-/**
-* Fetch many user documents by ID in a single component round-trip.
-*
-* Equivalent to calling {@link userGetById} for each ID in parallel from the
-* app side, but collapses what would be `N` cross-component RPCs into one.
-* Returns the documents in the same order as the input IDs; missing users
-* appear as `null`. Input is de-duplicated internally so passing the same
-* ID twice costs exactly one `ctx.db.get`.
-*
-* Hot paths like `groups:getDashboard` (member summaries) and
-* `issues:projectIssues` (assignee/creator lookups) previously fanned out
-* N `userGetById` calls — this helper is the batched replacement.
-*
-* @param args.userIds - Array of user document IDs (order preserved, duplicates tolerated).
-* @returns Array of user documents or `null` entries, in the same order as `args.userIds`.
-*
-* @example
-* ```ts
-* const users = await ctx.runQuery(
-*   component.identity.users.userGetMany,
-*   { userIds: memberIds },
-* );
-* const byId = new Map(users.filter(u => u !== null).map(u => [u!._id, u!]));
-* ```
-*/
-const userGetMany = query({
-	args: { userIds: v.array(v.id("User")) },
-	returns: v.array(v.union(vUserDoc, v.null())),
-	handler: async (ctx, { userIds }) => {
-		if (userIds.length === 0) return [];
-		const unique = Array.from(new Set(userIds));
-		const docs = await Promise.all(unique.map((id) => ctx.db.get("User", id)));
-		const byId = new Map(unique.map((id, i) => [id, docs[i] ?? null]));
-		return userIds.map((id) => byId.get(id) ?? null);
-	}
-});
-/**
-* 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}`);
-* }
-* ```
-*/
-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", void 0)).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}`);
-* }
-* ```
-*/
-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", void 0)).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
@@ -219,19 +77,6 @@ const userFindByVerifiedPhone = query({
 *   `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,
-*     },
-*   },
-* );
-* ```
 */
 const userInsert = mutation({
 	args: { data: v.any() },
@@ -255,17 +100,6 @@ const userInsert = mutation({
 *   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" },
-*   },
-* );
-* ```
 */
 const userUpsert = mutation({
 	args: {
@@ -293,16 +127,6 @@ const userUpsert = mutation({
 * @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" },
-*   },
-* );
-* ```
 */
 const userPatch = mutation({
 	args: {
@@ -325,13 +149,6 @@ const userPatch = mutation({
 * @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 },
-* );
-* ```
 */
 const userDelete = mutation({
 	args: {
@@ -375,11 +192,197 @@ const userDelete = mutation({
 				...totps.map((t) => ctx.db.delete("TotpFactor", t._id))
 			]);
 		}
+		const ownedEmails = await ctx.db.query("UserEmail").withIndex("user_id", (q) => q.eq("userId", userId)).collect();
+		await Promise.all(ownedEmails.map((e) => ctx.db.delete("UserEmail", e._id)));
 		await ctx.db.delete("User", userId);
 		return null;
 	}
 });
+/**
+* List every email a user owns (across providers/SSO connections).
+*
+* @param args.userId - The user whose emails to list.
+* @returns The user's `UserEmail` documents (may be empty).
+*
+*/
+const userEmailListByUser = query({
+	args: { userId: v.id("User") },
+	returns: v.array(vUserEmailDoc),
+	handler: async (ctx, { userId }) => {
+		return await ctx.db.query("UserEmail").withIndex("user_id", (q) => q.eq("userId", userId)).collect();
+	}
+});
+/**
+* Find a verified-email owner, optionally scoped to a single SSO
+* connection. Returns the matching user document if exactly one verified
+* `UserEmail` matches (preserving the "one-or-null" linking contract).
+*
+* Pass `connectionId` for SSO logins so a verified email only matches a
+* row asserted by that same connection — never across IdPs.
+*
+* @param args.email - Email address (exact match).
+* @param args.connectionId - Restrict to this connection's emails (SSO).
+* @returns The owning user document, or `null` when zero or 2+ match.
+*
+*/
+const userEmailOwner = query({
+	args: {
+		email: v.string(),
+		connectionId: v.optional(v.id("GroupConnection"))
+	},
+	returns: v.union(vUserDoc, v.null()),
+	handler: async (ctx, { email, connectionId }) => {
+		const rows = connectionId === void 0 ? await ctx.db.query("UserEmail").withIndex("email_verified", (q) => q.eq("email", email).gt("verificationTime", void 0)).take(2) : (await ctx.db.query("UserEmail").withIndex("connection_id_email", (q) => q.eq("connectionId", connectionId).eq("email", email)).take(2)).filter((r) => typeof r.verificationTime === "number");
+		if (rows.length !== 1) return null;
+		return await ctx.db.get("User", rows[0].userId);
+	}
+});
+/**
+* Record (insert or update) an email a user owns. When `isPrimary` is
+* `true`, any existing primary for the user is demoted and the
+* denormalized `User.email` / `emailVerificationTime` pointer is synced.
+*
+* Keyed by `(userId, email)`. Provenance (`source`, `connectionId`,
+* `accountId`, `provider`) is recorded so SSO linking can stay
+* connection-scoped.
+*
+* @param args.userId - Owner of the email.
+* @param args.email - The email address (store lowercased).
+* @param args.verified - Mark verified (sets `verificationTime`).
+* @param args.isPrimary - Promote to the user's primary email.
+* @param args.source - Which mechanism asserted it (`oauth`, `saml`, …).
+* @param args.accountId - Originating account, when applicable.
+* @param args.provider - Originating provider id, when applicable.
+* @param args.connectionId - Originating SSO connection, when applicable.
+* @returns The `UserEmail` document ID.
+*
+*/
+const userEmailUpsert = mutation({
+	args: {
+		userId: v.id("User"),
+		email: v.string(),
+		verified: v.optional(v.boolean()),
+		isPrimary: v.optional(v.boolean()),
+		source: vUserEmailSource,
+		accountId: v.optional(v.id("Account")),
+		provider: v.optional(v.string()),
+		connectionId: v.optional(v.id("GroupConnection"))
+	},
+	returns: v.id("UserEmail"),
+	handler: async (ctx, args) => {
+		const owned = await ctx.db.query("UserEmail").withIndex("user_id", (q) => q.eq("userId", args.userId)).collect();
+		const existing = owned.find((e) => e.email === args.email) ?? null;
+		const makePrimary = args.isPrimary === true || owned.length === 0;
+		const verificationTime = args.verified === true ? existing?.verificationTime ?? Date.now() : existing?.verificationTime;
+		if (makePrimary) await Promise.all(owned.filter((e) => e.isPrimary && e._id !== existing?._id).map((e) => ctx.db.patch("UserEmail", e._id, { isPrimary: false })));
+		let id;
+		if (existing !== null) {
+			await ctx.db.patch("UserEmail", existing._id, {
+				verificationTime,
+				isPrimary: makePrimary ? true : existing.isPrimary,
+				source: args.source,
+				accountId: args.accountId ?? existing.accountId,
+				provider: args.provider ?? existing.provider,
+				connectionId: args.connectionId ?? existing.connectionId
+			});
+			id = existing._id;
+		} else id = await ctx.db.insert("UserEmail", {
+			userId: args.userId,
+			email: args.email,
+			verificationTime,
+			isPrimary: makePrimary,
+			source: args.source,
+			accountId: args.accountId,
+			provider: args.provider,
+			connectionId: args.connectionId
+		});
+		if (makePrimary) await ctx.db.patch("User", args.userId, {
+			email: args.email,
+			...verificationTime !== void 0 ? { emailVerificationTime: verificationTime } : {}
+		});
+		return id;
+	}
+});
+/**
+* Promote one of the user's emails to primary, syncing the denormalized
+* `User.email` / `emailVerificationTime` pointer. The target must exist
+* and be verified.
+*
+* @param args.userId - Owner of the email.
+* @param args.email - The address to promote (must be owned + verified).
+* @returns `null`.
+* @throws `INVALID_PARAMETERS` if the email is not owned or not verified.
+*
+*/
+const userEmailSetPrimary = mutation({
+	args: {
+		userId: v.id("User"),
+		email: v.string()
+	},
+	returns: v.null(),
+	handler: async (ctx, { userId, email }) => {
+		const owned = await ctx.db.query("UserEmail").withIndex("user_id", (q) => q.eq("userId", userId)).collect();
+		const target = owned.find((e) => e.email === email);
+		if (target === void 0) throw new ConvexError({
+			code: "INVALID_PARAMETERS",
+			message: "Email is not owned by this user."
+		});
+		if (target.verificationTime === void 0) throw new ConvexError({
+			code: "INVALID_PARAMETERS",
+			message: "Cannot make an unverified email primary."
+		});
+		await Promise.all(owned.filter((e) => e.isPrimary && e._id !== target._id).map((e) => ctx.db.patch("UserEmail", e._id, { isPrimary: false })));
+		await ctx.db.patch("UserEmail", target._id, { isPrimary: true });
+		await ctx.db.patch("User", userId, {
+			email: target.email,
+			emailVerificationTime: target.verificationTime
+		});
+		return null;
+	}
+});
+/**
+* Remove an email a user owns. Guards: cannot remove the primary, the
+* last verified email, or a connection-managed row (`saml`/`oidc`/`scim`
+* with a `connectionId` — owned by the IdP/SCIM, not the user).
+*
+* @param args.userId - Owner of the email.
+* @param args.email - The address to remove (must be owned).
+* @returns `null`.
+* @throws `INVALID_PARAMETERS` if not owned, primary, the only verified
+*   email, or connection-managed.
+*
+*/
+const userEmailRemove = mutation({
+	args: {
+		userId: v.id("User"),
+		email: v.string()
+	},
+	returns: v.null(),
+	handler: async (ctx, { userId, email }) => {
+		const owned = await ctx.db.query("UserEmail").withIndex("user_id", (q) => q.eq("userId", userId)).collect();
+		const target = owned.find((e) => e.email === email);
+		if (target === void 0) throw new ConvexError({
+			code: "INVALID_PARAMETERS",
+			message: "Email is not owned by this user."
+		});
+		if (target.isPrimary) throw new ConvexError({
+			code: "INVALID_PARAMETERS",
+			message: "Cannot remove the primary email; set another primary first."
+		});
+		if (target.connectionId !== void 0 && (target.source === "saml" || target.source === "oidc" || target.source === "scim")) throw new ConvexError({
+			code: "INVALID_PARAMETERS",
+			message: "This email is managed by an SSO/SCIM connection."
+		});
+		const verifiedCount = owned.filter((e) => e.verificationTime !== void 0).length;
+		if (target.verificationTime !== void 0 && verifiedCount <= 1) throw new ConvexError({
+			code: "INVALID_PARAMETERS",
+			message: "Cannot remove the only verified email."
+		});
+		await ctx.db.delete("UserEmail", target._id);
+		return null;
+	}
+});
 
 //#endregion
-export { userDelete, userFindByVerifiedEmail, userFindByVerifiedPhone, userGetById, userGetMany, userInsert, userList, userPatch, userUpsert };
+export { userDelete, userEmailListByUser, userEmailOwner, userEmailRemove, userEmailSetPrimary, userEmailUpsert, userInsert, userList, userPatch, userUpsert };
 //# sourceMappingURL=users.js.map

package/dist/component/public/identity/verifiers.js

@@ -21,13 +21,6 @@ async function getUnexpiredVerifier(ctx, verifierId) {
 *   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 },
-* );
-* ```
 */
 const verifierCreate = mutation({
 	args: {
@@ -45,61 +38,24 @@ const verifierCreate = mutation({
 	}
 });
 /**
-* 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}`);
-* }
-* ```
+* Read a verifier by identity — one function, all-optional args, unioned
+* return: `{ id }` (point lookup) or `{ signature }` (unique index).
+* Expiry enforced for both.
 */
-const verifierGetById = query({
-	args: { verifierId: v.id("AuthVerifier") },
-	returns: v.union(vAuthVerifierDoc, v.null()),
-	handler: async (ctx, { verifierId }) => {
-		return await getUnexpiredVerifier(ctx, 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");
-* }
-* ```
-*/
-const verifierGetBySignature = query({
-	args: { signature: v.string() },
+const verifierGet = query({
+	args: {
+		id: v.optional(v.id("AuthVerifier")),
+		signature: v.optional(v.string())
+	},
 	returns: v.union(vAuthVerifierDoc, v.null()),
-	handler: async (ctx, { signature }) => {
-		const verifier = await ctx.db.query("AuthVerifier").withIndex("signature", (q) => q.eq("signature", signature)).unique();
-		if (verifier?.expirationTime !== void 0 && verifier.expirationTime < Date.now()) return null;
-		return verifier;
+	handler: async (ctx, args) => {
+		if (args.signature !== void 0) {
+			const verifier = await ctx.db.query("AuthVerifier").withIndex("signature", (q) => q.eq("signature", args.signature)).unique();
+			if (verifier?.expirationTime !== void 0 && verifier.expirationTime < Date.now()) return null;
+			return verifier;
+		}
+		if (args.id === void 0) return null;
+		return await getUnexpiredVerifier(ctx, args.id);
 	}
 });
 /**
@@ -114,17 +70,6 @@ const verifierGetBySignature = query({
 *   (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 },
-*   },
-* );
-* ```
 */
 const verifierPatch = mutation({
 	args: {
@@ -147,14 +92,6 @@ const verifierPatch = mutation({
 * @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 },
-* );
-* ```
 */
 const verifierDelete = mutation({
 	args: { verifierId: v.id("AuthVerifier") },
@@ -166,5 +103,5 @@ const verifierDelete = mutation({
 });
 
 //#endregion
-export { verifierCreate, verifierDelete, verifierGetById, verifierGetBySignature, verifierPatch };
+export { verifierCreate, verifierDelete, verifierGet, verifierPatch };
 //# sourceMappingURL=verifiers.js.map