@estifanos-sh/convex-auth 0.0.1-preview.0

package/dist/component/token/refresh.js

@@ -0,0 +1,189 @@
+import { vRefreshTokenDoc, vUserDoc } from "../model.js";
+import { mutation, query } from "../_generated/server.js";
+import { v } from "convex/values";
+
+//#region src/component/token/refresh.ts
+/**
+* `component.token.refresh.*` — session refresh tokens.
+*
+* Reads collapse into one overloaded `get`;
+* `exchange` is a kept domain verb (rotation with replay detection).
+*
+* @module
+*/
+/**
+* Upper bound on a session's RefreshToken rows deleted in one cleanup. The
+* session row is deleted first (so revocation is effective immediately); any
+* rows beyond this cap are inert — they reference a now-deleted session and are
+* reaped by the expiration cron — so a session with a pathologically large token
+* count can't make the cleanup exceed Convex read limits and roll back.
+*/
+const SESSION_TOKEN_DELETE_BATCH = 1024;
+/**
+* Read a refresh token by `id`, or the session's currently-active (unused)
+* token via `activeForSession`. Accepts exactly one selector.
+*/
+const get = query({
+	args: {
+		id: v.optional(v.id("RefreshToken")),
+		activeForSession: v.optional(v.id("Session"))
+	},
+	returns: v.union(vRefreshTokenDoc, v.null()),
+	handler: async (ctx, args) => {
+		if (args.activeForSession !== void 0) return await ctx.db.query("RefreshToken").withIndex("session_id_first_used", (q) => q.eq("sessionId", args.activeForSession).eq("firstUsedTime", void 0)).order("desc").first();
+		if (args.id === void 0) return null;
+		return await ctx.db.get("RefreshToken", args.id);
+	}
+});
+/**
+* List up to `SESSION_TOKEN_DELETE_BATCH` refresh tokens for a session, or only
+* the children of `parentRefreshTokenId` when supplied.
+*/
+const list = query({
+	args: {
+		sessionId: v.id("Session"),
+		parentRefreshTokenId: v.optional(v.id("RefreshToken"))
+	},
+	returns: v.array(vRefreshTokenDoc),
+	handler: async (ctx, { sessionId, parentRefreshTokenId }) => {
+		if (parentRefreshTokenId !== void 0) return await ctx.db.query("RefreshToken").withIndex("session_id_parent_refresh_token_id", (q) => q.eq("sessionId", sessionId).eq("parentRefreshTokenId", parentRefreshTokenId)).take(SESSION_TOKEN_DELETE_BATCH);
+		return await ctx.db.query("RefreshToken").withIndex("session_id", (q) => q.eq("sessionId", sessionId)).take(SESSION_TOKEN_DELETE_BATCH);
+	}
+});
+/** Create a refresh token for a session. Returns the new id. */
+const create = 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);
+	}
+});
+/** Patch a refresh token in place. */
+const update = mutation({
+	args: {
+		id: v.id("RefreshToken"),
+		patch: v.object({
+			expirationTime: v.optional(v.number()),
+			firstUsedTime: v.optional(v.number())
+		})
+	},
+	returns: v.null(),
+	handler: async (ctx, { id: refreshTokenId, patch }) => {
+		await ctx.db.patch("RefreshToken", refreshTokenId, patch);
+		return null;
+	}
+});
+/** Delete all refresh tokens for a session. */
+const remove = mutation({
+	args: { sessionId: v.id("Session") },
+	returns: v.null(),
+	handler: async (ctx, { sessionId }) => {
+		const tokens = await ctx.db.query("RefreshToken").withIndex("session_id", (q) => q.eq("sessionId", sessionId)).take(SESSION_TOKEN_DELETE_BATCH);
+		await Promise.all(tokens.map((token) => ctx.db.delete("RefreshToken", token._id)));
+		return null;
+	}
+});
+const refreshSessionExchangeResult = v.union(v.object({
+	status: v.literal("rotated"),
+	userId: v.id("User"),
+	user: vUserDoc,
+	sessionId: v.id("Session"),
+	refreshTokenId: v.id("RefreshToken")
+}), v.object({
+	status: v.literal("reuse_detected"),
+	userId: v.id("User"),
+	refreshTokenId: v.id("RefreshToken")
+}), v.object({ status: v.literal("invalid") }));
+/**
+* Rotate a refresh token, returning a `status`-tagged result. `"rotated"` (first
+* use, an in-window replay, or the already-issued active child) carries the
+* user/session/token ids for the next access token. `"reuse_detected"` (a replay
+* of an already-rotated token outside `reuseWindowMs`) is theft: the session and
+* all of its refresh tokens are deleted (forcing re-authentication) and the
+* user/token are returned so the server can audit it. `"invalid"` (a missing,
+* mismatched, or expired token, or a missing/expired session) carries nothing;
+* the session and its tokens are deleted in every such case except a token that
+* belongs to another session, which is left untouched.
+*/
+const exchange = mutation({
+	args: {
+		refreshTokenId: v.id("RefreshToken"),
+		sessionId: v.id("Session"),
+		now: v.number(),
+		refreshTokenExpirationTime: v.number(),
+		reuseWindowMs: v.number()
+	},
+	returns: refreshSessionExchangeResult,
+	handler: async (ctx, args) => {
+		const cleanupSessionArtifacts = async () => {
+			if (await ctx.db.get("Session", args.sessionId) !== null) await ctx.db.delete("Session", args.sessionId);
+			const tokens = await ctx.db.query("RefreshToken").withIndex("session_id", (q) => q.eq("sessionId", args.sessionId)).take(SESSION_TOKEN_DELETE_BATCH);
+			await Promise.all(tokens.map((token) => ctx.db.delete("RefreshToken", token._id)));
+		};
+		const refreshTokenDoc = await ctx.db.get("RefreshToken", args.refreshTokenId);
+		if (refreshTokenDoc === null || refreshTokenDoc.sessionId !== args.sessionId) return { status: "invalid" };
+		if (refreshTokenDoc.expirationTime < args.now) {
+			await cleanupSessionArtifacts();
+			return { status: "invalid" };
+		}
+		const session = await ctx.db.get("Session", args.sessionId);
+		if (session === null || session.expirationTime < args.now) {
+			await cleanupSessionArtifacts();
+			return { status: "invalid" };
+		}
+		const user = await ctx.db.get("User", session.userId);
+		if (user === null) {
+			await cleanupSessionArtifacts();
+			return { status: "invalid" };
+		}
+		const issueRefreshToken = () => ctx.db.insert("RefreshToken", {
+			sessionId: args.sessionId,
+			expirationTime: args.refreshTokenExpirationTime,
+			parentRefreshTokenId: args.refreshTokenId
+		});
+		if (refreshTokenDoc.firstUsedTime === void 0) {
+			await ctx.db.patch("RefreshToken", args.refreshTokenId, { firstUsedTime: args.now });
+			const refreshTokenId = await issueRefreshToken();
+			return {
+				status: "rotated",
+				userId: session.userId,
+				user,
+				sessionId: args.sessionId,
+				refreshTokenId
+			};
+		}
+		const activeRefreshToken = await ctx.db.query("RefreshToken").withIndex("session_id_first_used", (q) => q.eq("sessionId", args.sessionId).eq("firstUsedTime", void 0)).order("desc").first();
+		if (activeRefreshToken !== null && activeRefreshToken.parentRefreshTokenId === args.refreshTokenId) return {
+			status: "rotated",
+			userId: session.userId,
+			user,
+			sessionId: args.sessionId,
+			refreshTokenId: activeRefreshToken._id
+		};
+		if (refreshTokenDoc.firstUsedTime + args.reuseWindowMs > args.now) {
+			const refreshTokenId = await issueRefreshToken();
+			return {
+				status: "rotated",
+				userId: session.userId,
+				user,
+				sessionId: args.sessionId,
+				refreshTokenId
+			};
+		}
+		const reuseUserId = session.userId;
+		await cleanupSessionArtifacts();
+		return {
+			status: "reuse_detected",
+			userId: reuseUserId,
+			refreshTokenId: args.refreshTokenId
+		};
+	}
+});
+
+//#endregion
+export { create, exchange, get, list, remove, update };
+//# sourceMappingURL=refresh.js.map

package/dist/component/token/verification.js

@@ -0,0 +1,155 @@
+import { vAccountDoc, vUserDoc, vVerificationCodeDoc } from "../model.js";
+import { mutation, query } from "../_generated/server.js";
+import { recordSignInLimit, resetSignInLimit } from "../limits.js";
+import { createSessionRows } from "../session.js";
+import { v } from "convex/values";
+import { getOneFrom } from "convex-helpers/server/relationships";
+
+//#region src/component/token/verification.ts
+/**
+* `component.token.verification.*` — OTP / magic-link / OAuth codes.
+*
+* Reads collapse into one overloaded `get`.
+*
+* @module
+*/
+/** Reserve verification attempts and resolve a valid code plus account atomically. */
+const beginVerification = mutation({
+	args: {
+		code: v.string(),
+		identifier: v.optional(v.string()),
+		verifier: v.optional(v.string()),
+		provider: v.optional(v.string()),
+		maxAttemptsPerHour: v.number(),
+		now: v.number()
+	},
+	returns: v.union(v.object({ status: v.literal("invalid") }), v.object({ status: v.literal("limited") }), v.object({
+		status: v.literal("ready"),
+		code: vVerificationCodeDoc,
+		account: vAccountDoc
+	})),
+	handler: async (ctx, args) => {
+		if (args.identifier !== void 0) {
+			if (!(await recordSignInLimit(ctx, {
+				identifier: args.identifier,
+				maxAttemptsPerHour: args.maxAttemptsPerHour
+			})).ok) return { status: "limited" };
+		}
+		const code = await ctx.db.query("VerificationCode").withIndex("code", (q) => q.eq("code", args.code)).first();
+		if (code === null) return { status: "invalid" };
+		const accountKey = `accountId:${code.accountId}`;
+		if (accountKey !== args.identifier) {
+			if (!(await recordSignInLimit(ctx, {
+				identifier: accountKey,
+				maxAttemptsPerHour: args.maxAttemptsPerHour
+			})).ok) return { status: "limited" };
+		}
+		if (code.verifier !== args.verifier || code.expirationTime < args.now || args.provider !== void 0 && code.provider !== args.provider) return { status: "invalid" };
+		const account = await ctx.db.get("Account", code.accountId);
+		return account === null ? { status: "invalid" } : {
+			status: "ready",
+			code,
+			account
+		};
+	}
+});
+/** Consume a verified code, clear its limits, and issue its session atomically. */
+const completeVerification = mutation({
+	args: {
+		codeId: v.id("VerificationCode"),
+		userId: v.id("User"),
+		identifier: v.optional(v.string()),
+		replaceSessionId: v.optional(v.id("Session")),
+		generateTokens: v.boolean(),
+		sessionExpirationTime: v.number(),
+		refreshTokenExpirationTime: v.number()
+	},
+	returns: v.union(v.object({ status: v.literal("rejected") }), v.object({
+		status: v.literal("accepted"),
+		user: vUserDoc,
+		sessionId: v.id("Session"),
+		refreshTokenId: v.optional(v.id("RefreshToken")),
+		replacedSessionId: v.optional(v.id("Session"))
+	})),
+	handler: async (ctx, args) => {
+		const code = await ctx.db.get("VerificationCode", args.codeId);
+		if (code === null) return { status: "rejected" };
+		await ctx.db.delete("VerificationCode", code._id);
+		const limitKeys = new Set([`accountId:${code.accountId}`]);
+		if (args.identifier !== void 0) limitKeys.add(args.identifier);
+		for (const key of limitKeys) await resetSignInLimit(ctx, key);
+		const created = await createSessionRows(ctx, {
+			userId: args.userId,
+			replaceSessionId: args.replaceSessionId,
+			sessionExpirationTime: args.sessionExpirationTime,
+			refreshTokenExpirationTime: args.generateTokens ? args.refreshTokenExpirationTime : void 0
+		});
+		if (created === null) return { status: "rejected" };
+		return {
+			status: "accepted",
+			user: created.user,
+			sessionId: created.sessionId,
+			...created.refreshTokenId === void 0 ? {} : { refreshTokenId: created.refreshTokenId },
+			...created.replacedSessionId === void 0 ? {} : { replacedSessionId: created.replacedSessionId }
+		};
+	}
+});
+/** Refund a valid code attempt when later provider or provisioning work fails. */
+const resetVerificationLimits = mutation({
+	args: {
+		accountId: v.id("Account"),
+		identifier: v.optional(v.string())
+	},
+	returns: v.null(),
+	handler: async (ctx, args) => {
+		const limitKeys = new Set([`accountId:${args.accountId}`]);
+		if (args.identifier !== void 0) limitKeys.add(args.identifier);
+		for (const key of limitKeys) await resetSignInLimit(ctx, key);
+		return null;
+	}
+});
+/**
+* Read a verification code by raw `code` or by `accountId`.
+* Accepts exactly one selector.
+*/
+const get = query({
+	args: {
+		accountId: v.optional(v.id("Account")),
+		code: v.optional(v.string())
+	},
+	returns: v.union(vVerificationCodeDoc, v.null()),
+	handler: async (ctx, args) => {
+		if (args.code !== void 0) return await ctx.db.query("VerificationCode").withIndex("code", (q) => q.eq("code", args.code)).first();
+		if (args.accountId === void 0) return null;
+		return await getOneFrom(ctx.db, "VerificationCode", "account_id", args.accountId, "accountId");
+	}
+});
+/** Create a verification code for an account. Returns the new id. */
+const create = 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);
+	}
+});
+/** Delete a verification code by id. */
+const remove = mutation({
+	args: { id: v.id("VerificationCode") },
+	returns: v.null(),
+	handler: async (ctx, { id: verificationCodeId }) => {
+		await ctx.db.delete("VerificationCode", verificationCodeId);
+		return null;
+	}
+});
+
+//#endregion
+export { beginVerification, completeVerification, create, get, remove, resetVerificationLimits };
+//# sourceMappingURL=verification.js.map

package/dist/component/user/email.js

@@ -0,0 +1,147 @@
+import { ErrorCode } from "../../shared/codes.js";
+import { vUserEmailDoc, vUserEmailSource } from "../model.js";
+import { mutation, query } from "../_generated/server.js";
+import { ConvexError, v } from "convex/values";
+
+//#region src/component/user/email.ts
+/**
+* `component.user.email.*` — emails a user owns (sub-resource of user).
+*
+* Mirrors the consumer facade `auth.user.email.{list,add,remove,
+* primary}`.
+*
+* @module
+*/
+const USER_EMAIL_BATCH = 64;
+async function listOwnedEmails(ctx, userId) {
+	const owned = await ctx.db.query("UserEmail").withIndex("user_id", (q) => q.eq("userId", userId)).take(USER_EMAIL_BATCH + 1);
+	if (owned.length > USER_EMAIL_BATCH) throw new ConvexError({
+		code: ErrorCode.INVALID_PARAMETERS,
+		message: `User has more than ${USER_EMAIL_BATCH} emails; operation is not safe in one mutation.`
+	});
+	return owned;
+}
+/** List the emails owned by a user. */
+const list = 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)).take(USER_EMAIL_BATCH);
+	}
+});
+/**
+* Add an email to a user, or patch it when the address already exists.
+* Promotes it to primary when `isPrimary` is set or it is the user's first
+* email, demoting any prior primary and syncing the denormalized `User.email`.
+*/
+const upsert = 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, existing] = await Promise.all([listOwnedEmails(ctx, args.userId), ctx.db.query("UserEmail").withIndex("user_id_email", (q) => q.eq("userId", args.userId).eq("email", args.email)).first()]);
+		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;
+	}
+});
+/**
+* Make one of a user's verified emails primary, demoting the previous primary
+* and syncing `User.email`. Rejects unowned or unverified emails.
+*/
+const promote = mutation({
+	args: {
+		userId: v.id("User"),
+		email: v.string()
+	},
+	returns: v.null(),
+	handler: async (ctx, { userId, email }) => {
+		const [owned, target] = await Promise.all([listOwnedEmails(ctx, userId), ctx.db.query("UserEmail").withIndex("user_id_email", (q) => q.eq("userId", userId).eq("email", email)).first()]);
+		if (target === null) throw new ConvexError({
+			code: ErrorCode.INVALID_PARAMETERS,
+			message: "Email is not owned by this user."
+		});
+		if (target.verificationTime === void 0) throw new ConvexError({
+			code: ErrorCode.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. Refuses the primary email, the only verified
+* email, and emails managed by a SAML/OIDC/SCIM connection.
+*/
+const remove = mutation({
+	args: {
+		userId: v.id("User"),
+		email: v.string()
+	},
+	returns: v.null(),
+	handler: async (ctx, { userId, email }) => {
+		const [owned, target] = await Promise.all([listOwnedEmails(ctx, userId), ctx.db.query("UserEmail").withIndex("user_id_email", (q) => q.eq("userId", userId).eq("email", email)).first()]);
+		if (target === null) throw new ConvexError({
+			code: ErrorCode.INVALID_PARAMETERS,
+			message: "Email is not owned by this user."
+		});
+		if (target.isPrimary) throw new ConvexError({
+			code: ErrorCode.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: ErrorCode.INVALID_PARAMETERS,
+			message: "This email is managed by an Connection/SCIM connection."
+		});
+		const verifiedCount = owned.filter((e) => e.verificationTime !== void 0).length;
+		if (target.verificationTime !== void 0 && verifiedCount <= 1) throw new ConvexError({
+			code: ErrorCode.INVALID_PARAMETERS,
+			message: "Cannot remove the only verified email."
+		});
+		await ctx.db.delete("UserEmail", target._id);
+		return null;
+	}
+});
+
+//#endregion
+export { list, promote, remove, upsert };
+//# sourceMappingURL=email.js.map