@usequark/quark-create-app 1.25.16 → 1.26.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usequark/quark-create-app",
-  "version": "1.25.16",
+  "version": "1.26.0",
   "description": "CLI to scaffold new Quark projects with Next.js, Prisma, BullMQ, and Railway deployment",
   "keywords": [
     "quark",

package/templates/base-project/apps/web/src/app/api/auth/forgot-password/route.js

@@ -0,0 +1,57 @@
+import {
+	createLogger,
+	validateBody,
+	withCsrfProtection,
+} from "@usequark/quark-core/core";
+import { user } from "@usequark/quark-db";
+import { NextResponse } from "next/server";
+import { z } from "zod";
+import { sendResetPasswordEmail } from "@/lib/send-reset-password-email";
+import { handleError } from "../../error-handler";
+
+const logger = createLogger("auth:forgot-password");
+
+const forgotPasswordSchema = z.object({
+	email: z.string().email("Invalid email address"),
+});
+
+/**
+ * The response for every request, registered address or not.
+ *
+ * Replying differently for unknown addresses turns this route into an
+ * email-enumeration oracle: the difference between "no such user" and "check
+ * your inbox" is exactly the information a spammer or a spear-phisher is
+ * probing for. The same 200 with the same body is also what the rate limiter
+ * needs — a distinguishable error path would let an attacker distinguish
+ * "limited" from "not a valid address" from the outside.
+ */
+const NEUTRAL_RESPONSE = {
+	message: "If that email address has an account, a reset link is on its way.",
+};
+
+export const POST = withCsrfProtection(async (request) => {
+	try {
+		const { email } = await validateBody(request, forgotPasswordSchema);
+
+		const account = await user.findByEmail(email);
+
+		if (account) {
+			try {
+				await sendResetPasswordEmail(account);
+			} catch (error) {
+				// The address exists; the answer must still be the neutral one. A
+				// failure here is operational (token issue or queue down), so it is
+				// logged where an operator can see it and deliberately not surfaced
+				// to the caller.
+				logger.error("Failed to send password reset email", {
+					userId: account.id,
+					message: error?.message ?? String(error),
+				});
+			}
+		}
+
+		return NextResponse.json(NEUTRAL_RESPONSE);
+	} catch (error) {
+		return handleError(error);
+	}
+});

package/templates/base-project/apps/web/src/app/api/auth/register/route.js

@@ -1,11 +1,18 @@
 import { hashPassword } from "@usequark/quark-core/auth";
-import { validateBody, withCsrfProtection } from "@usequark/quark-core/core";
+import {
+	createLogger,
+	validateBody,
+	withCsrfProtection,
+} from "@usequark/quark-core/core";
 import { user, userRegisterSchema } from "@usequark/quark-db";
 import { NextResponse } from "next/server";
 import { isSignupEnabled } from "@/lib/auth-signup";
 import { enqueueWelcomeEmail } from "@/lib/enqueue-welcome-email";
+import { sendVerificationEmail } from "@/lib/send-verification-email";
 import { handleError } from "../../error-handler";
 
+const logger = createLogger("auth:register");
+
 export const POST = withCsrfProtection(async (request) => {
 	if (!isSignupEnabled()) {
 		return NextResponse.json(
@@ -51,6 +58,18 @@ export const POST = withCsrfProtection(async (request) => {
 			// Non-critical - user is created even if email fails to enqueue
 		}
 
+		// Issue and enqueue the email-verification link. Equally non-fatal: the
+		// account exists either way, and an unverified address is not (yet) a
+		// gated account — it just has no confirmation on file.
+		try {
+			await sendVerificationEmail(newUser);
+		} catch (error) {
+			logger.error("Failed to send verification email", {
+				userId: newUser.id,
+				message: error?.message ?? String(error),
+			});
+		}
+
 		return NextResponse.json(safeUser, { status: 201 });
 	} catch (error) {
 		return handleError(error);

package/templates/base-project/apps/web/src/app/api/auth/reset-password/route.js

@@ -0,0 +1,104 @@
+import { hashPassword, hashToken } from "@usequark/quark-core/auth";
+import { validateBody, withCsrfProtection } from "@usequark/quark-core/core";
+import { ValidationError } from "@usequark/quark-core/errors";
+import { passwordSchema, user, verificationToken } from "@usequark/quark-db";
+import { NextResponse } from "next/server";
+import { z } from "zod";
+import { handleError } from "../../error-handler";
+
+const resetPasswordSchema = z.object({
+	token: z.string().min(1, "A reset token is required"),
+	password: passwordSchema,
+});
+
+/**
+ * The message used for every refused reset: unknown token, expired token, or
+ * account gone. An attacker probing a stolen link learns nothing from which
+ * wording comes back, because they are the same.
+ */
+const UNUSABLE_LINK_MESSAGE =
+	"This reset link is invalid or has expired. Request a new one.";
+
+/**
+ * Loads the token row for a presented token, or null when there is none usable.
+ *
+ * The row is found by the SHA-256 digest, never by the raw value — that is the
+ * entire point of storing the digest in the first place. Expiry is checked
+ * here so both GET and POST agree on what "usable" means, and so a consumed
+ * (deleted) token is indistinguishable from one that never existed.
+ *
+ * @param {string | null} rawToken - The token from the link's query string.
+ * @returns {Promise<object | null>} The `VerificationToken` row, or null.
+ */
+async function resolveToken(rawToken) {
+	if (!rawToken) return null;
+
+	const record = await verificationToken.findByToken(hashToken(rawToken));
+	if (!record) return null;
+	if (record.expires.getTime() <= Date.now()) return null;
+
+	return record;
+}
+
+/**
+ * Answers whether a link is still usable, so the reset page can render the form
+ * or an error before the user types a new password into a dead form.
+ *
+ * GET is safe (no state change) and so is not CSRF-protected; the lookup is a
+ * single indexed primary-key read.
+ */
+export async function GET(request) {
+	try {
+		const token = new URL(request.url).searchParams.get("token");
+		const record = await resolveToken(token);
+
+		return NextResponse.json(
+			{ valid: Boolean(record) },
+			{ status: record ? 200 : 400 },
+		);
+	} catch (error) {
+		return handleError(error);
+	}
+}
+
+export const POST = withCsrfProtection(async (request) => {
+	try {
+		const { token, password } = await validateBody(
+			request,
+			resetPasswordSchema,
+		);
+		const record = await resolveToken(token);
+
+		if (!record) {
+			throw new ValidationError(UNUSABLE_LINK_MESSAGE);
+		}
+
+		const account = await user.findByEmail(record.identifier);
+		if (!account) {
+			// The account was deleted after the link was issued. The link is dead
+			// either way; burn the token so it cannot be tried a second time.
+			await verificationToken.deleteByIdentifier(record.identifier);
+			throw new ValidationError(UNUSABLE_LINK_MESSAGE);
+		}
+
+		const hashedPassword = await hashPassword(password);
+		await user.update(account.id, {
+			password: hashedPassword,
+			// Stamping the change is what reaches every live session (web JWT and
+			// mobile refresh token): `validateSessionToken` and the refresh route
+			// reject anything issued before this instant, so a password known to
+			// an attacker stops working the moment it is replaced.
+			passwordChangedAt: new Date(),
+		});
+
+		// Single-use: the token dies with the reset it performed. Replaying the
+		// same link must not overwrite the new password with another.
+		await verificationToken.deleteByIdentifier(account.email);
+
+		return NextResponse.json({
+			message: "Your password has been updated. You can now sign in.",
+		});
+	} catch (error) {
+		return handleError(error);
+	}
+});

package/templates/base-project/apps/web/src/app/api/auth/verify-email/route.js

@@ -0,0 +1,58 @@
+import { getAppUrl } from "@usequark/quark-config";
+import { hashToken } from "@usequark/quark-core/auth";
+import { createLogger } from "@usequark/quark-core/core";
+import { user, verificationToken } from "@usequark/quark-db";
+import { NextResponse } from "next/server";
+
+const logger = createLogger("auth:verify-email");
+
+/**
+ * Redeems an emailed verification link.
+ *
+ * A GET performs the state change because that is the shape of an emailed
+ * link — a mail client fetches it by navigation, not by posting JSON. The
+ * consequence is a bearer link: whoever holds it can confirm the address, so
+ * the same threat model as the reset flow applies — the token is 256 bits of
+ * randomness, stored only as a SHA-256 digest, and single-use.
+ *
+ * Outcomes funnel into the sign-in page through `?verified=`:
+ *   - `1`      - address confirmed (or already confirmed)
+ *   - `invalid` - no token, expired, consumed, or the account is gone
+ *   - `error`  - something broke server-side; logged, and the caller still
+ *     lands somewhere useful rather than on a bare 500
+ */
+export async function GET(request) {
+	const base = getAppUrl();
+
+	try {
+		const token = new URL(request.url).searchParams.get("token");
+		const record = token
+			? await verificationToken.findByToken(hashToken(token))
+			: null;
+
+		if (!record || record.expires.getTime() <= Date.now()) {
+			return NextResponse.redirect(`${base}/auth/signin?verified=invalid`);
+		}
+
+		const account = await user.findByEmail(record.identifier);
+		if (!account) {
+			// The account is gone; the confirmation would be for nobody. Burn the
+			// token and refuse rather than leaving a live link sitting in an
+			// inbox.
+			await verificationToken.deleteByIdentifier(record.identifier);
+			return NextResponse.redirect(`${base}/auth/signin?verified=invalid`);
+		}
+
+		if (!account.emailVerified) {
+			await user.update(account.id, { emailVerified: new Date() });
+		}
+		await verificationToken.deleteByIdentifier(account.email);
+
+		return NextResponse.redirect(`${base}/auth/signin?verified=1`);
+	} catch (error) {
+		logger.error("Email verification failed", {
+			message: error?.message ?? String(error),
+		});
+		return NextResponse.redirect(`${base}/auth/signin?verified=error`);
+	}
+}

package/templates/base-project/apps/web/src/app/auth/forgot-password/ForgotPasswordPageClient.js

@@ -0,0 +1,159 @@
+"use client";
+
+import { clearCsrfToken, getCsrfToken } from "@usequark/quark-core/csrf-client";
+import {
+	Button,
+	ErrorBanner,
+	Input,
+	Label,
+	QuarkLogo,
+} from "@usequark/quark-ui";
+import Link from "next/link";
+import { useState } from "react";
+
+/**
+ * The forgot-password form.
+ *
+ * The POST answers identically whether or not the address exists (see the
+ * route's enumeration note), so the client surface shows exactly one outcome:
+ * "if that address has an account, a link is on its way." A success state and a
+ * network-failure state, and deliberately nothing in between.
+ */
+export default function ForgotPasswordPageClient() {
+	const [email, setEmail] = useState("");
+	const [loading, setLoading] = useState(false);
+	const [error, setError] = useState("");
+	const [sent, setSent] = useState(false);
+
+	async function handleSubmit(e) {
+		e.preventDefault();
+		setError("");
+		setLoading(true);
+
+		try {
+			// Same pre-authentication CSRF handshake as the register page: fetch a
+			// token from GET /api/csrf and send it alongside the matching cookie.
+			let res = await postForgotPassword(await getCsrfToken());
+
+			// A 401 usually means the server rotated the csrf_token cookie out
+			// from under the cached token. Retry once with a fresh pair; a second
+			// failure is a real failure and falls through to the banner.
+			if (res.status === 401) {
+				clearCsrfToken();
+				res = await postForgotPassword(await getCsrfToken());
+			}
+
+			if (!res.ok && res.status !== 429) {
+				const body = await res.json().catch(() => ({}));
+				setError(body.message || "Something went wrong. Try again.");
+				setLoading(false);
+				return;
+			}
+
+			setSent(true);
+			setLoading(false);
+		} catch {
+			setError("Could not reach the server. Try again.");
+			setLoading(false);
+		}
+	}
+
+	async function postForgotPassword(csrfToken) {
+		return await fetch("/api/auth/forgot-password", {
+			method: "POST",
+			headers: {
+				"Content-Type": "application/json",
+				"X-CSRF-Token": csrfToken,
+			},
+			body: JSON.stringify({ email: email.trim() }),
+		});
+	}
+
+	return (
+		<div className="quark-auth-layout">
+			{/* Authority / branding panel */}
+			<div className="quark-auth-brand">
+				<Link href="/" aria-label="Go to home">
+					<QuarkLogo size={64} className="mb-8" />
+				</Link>
+				<p className="text-xs uppercase tracking-widest text-text-faint mb-3">
+					Account recovery
+				</p>
+				<h2 className="text-3xl font-bold text-text leading-tight mb-4">
+					Reset your password.
+				</h2>
+				<p className="text-sm text-text-muted leading-relaxed">
+					Enter your email and we will send you a link to recover access.
+				</p>
+			</div>
+
+			{/* Form panel */}
+			<div className="quark-auth-form">
+				{/* Mobile-only logo */}
+				<div className="flex md:hidden mb-8">
+					<Link href="/" aria-label="Go to home">
+						<QuarkLogo size={44} />
+					</Link>
+				</div>
+
+				<div className="quark-auth-panel w-full max-w-sm">
+					<div className="mb-8">
+						<h1 className="text-2xl font-bold tracking-tight text-text">
+							Forgot password
+						</h1>
+					</div>
+
+					<ErrorBanner message={error} />
+
+					{sent ? (
+						<>
+							<p
+								role="status"
+								className="text-sm text-text-muted leading-relaxed mb-8"
+							>
+								If that email address has an account, a reset link is on its
+								way. Check your inbox — the link expires after one hour.
+							</p>
+							<Link
+								href="/auth/signin"
+								className="text-xs text-text-muted hover:text-text transition-opacity duration-200 linear uppercase tracking-widest"
+							>
+								← Back to sign in
+							</Link>
+						</>
+					) : (
+						<form onSubmit={handleSubmit} className="space-y-5">
+							<div className="space-y-2">
+								<Label htmlFor="email">Email</Label>
+								<Input
+									id="email"
+									type="email"
+									autoComplete="email"
+									required
+									value={email}
+									onChange={(e) => setEmail(e.target.value)}
+								/>
+							</div>
+
+							<Button
+								type="submit"
+								variant="primary"
+								className="w-full mt-2"
+								disabled={loading}
+							>
+								{loading ? "Sending…" : "Send reset link →"}
+							</Button>
+
+							<Link
+								href="/auth/signin"
+								className="block text-center text-xs text-text-muted hover:text-text transition-opacity duration-200 linear uppercase tracking-widest"
+							>
+								← Back to sign in
+							</Link>
+						</form>
+					)}
+				</div>
+			</div>
+		</div>
+	);
+}

package/templates/base-project/apps/web/src/app/auth/forgot-password/page.js

@@ -1,58 +1,9 @@
-import { QuarkLogo } from "@usequark/quark-ui";
-import Link from "next/link";
+import ForgotPasswordPageClient from "./ForgotPasswordPageClient";
 
 export const metadata = {
 	title: "Forgot Password",
 };
 
 export default function ForgotPasswordPage() {
-	return (
-		<div className="quark-auth-layout">
-			{/* Authority / branding panel */}
-			<div className="quark-auth-brand">
-				<Link href="/" aria-label="Go to home">
-					<QuarkLogo size={64} className="mb-8" />
-				</Link>
-				<p className="text-xs uppercase tracking-widest text-text-faint mb-3">
-					Account recovery
-				</p>
-				<h2 className="text-3xl font-bold text-text leading-tight mb-4">
-					Reset your password.
-				</h2>
-				<p className="text-sm text-text-muted leading-relaxed">
-					Enter your email and we will send you a link to recover access.
-				</p>
-			</div>
-
-			{/* Form panel */}
-			<div className="quark-auth-form">
-				{/* Mobile-only logo */}
-				<div className="flex md:hidden mb-8">
-					<Link href="/" aria-label="Go to home">
-						<QuarkLogo size={44} />
-					</Link>
-				</div>
-
-				<div className="quark-auth-panel w-full max-w-sm">
-					<div className="mb-8">
-						<h1 className="text-2xl font-bold tracking-tight text-text">
-							Forgot password
-						</h1>
-					</div>
-
-					<p className="text-sm text-text-muted leading-relaxed mb-8">
-						Password reset is not available. Please contact support for help
-						accessing your account.
-					</p>
-
-					<Link
-						href="/auth/signin"
-						className="text-xs text-text-muted hover:text-text transition-opacity duration-200 linear uppercase tracking-widest"
-					>
-						← Back to sign in
-					</Link>
-				</div>
-			</div>
-		</div>
-	);
+	return <ForgotPasswordPageClient />;
 }

package/templates/base-project/apps/web/src/app/auth/reset-password/ResetPasswordPageClient.js

@@ -0,0 +1,280 @@
+"use client";
+
+import { clearCsrfToken, getCsrfToken } from "@usequark/quark-core/csrf-client";
+import {
+	Button,
+	ErrorBanner,
+	Label,
+	PasswordInput,
+	QuarkLogo,
+} from "@usequark/quark-ui";
+import Link from "next/link";
+import { useSearchParams } from "next/navigation";
+import { Suspense, useEffect, useState } from "react";
+
+const STRENGTH_LABELS = ["", "Weak", "Fair", "Good", "Strong"];
+const STRENGTH_COLORS = [
+	"",
+	"bg-danger",
+	"bg-warning",
+	"bg-primary",
+	"bg-success",
+];
+
+function getPasswordStrength(value) {
+	if (!value) return 0;
+	let score = 0;
+	if (value.length >= 8) score++;
+	if (/[a-z]/.test(value) && /[A-Z]/.test(value)) score++;
+	if (/\d/.test(value)) score++;
+	if (/[^a-zA-Z0-9]/.test(value)) score++;
+	return score;
+}
+
+function validatePassword(value) {
+	if (getPasswordStrength(value) < 3) {
+		return "Must be 8+ characters with uppercase, lowercase, and a number.";
+	}
+	return "";
+}
+
+export default function ResetPasswordPageClient() {
+	return (
+		<Suspense>
+			<ResetPasswordForm />
+		</Suspense>
+	);
+}
+
+function ResetPasswordForm() {
+	const searchParams = useSearchParams();
+	const token = searchParams.get("token") || "";
+
+	// `invalid` means the link is unusable (missing, expired, consumed).
+	// `error` means the validity check itself failed and the form stays down
+	// rather than letting a user type a new password into a form that might not
+	// work.
+	const [linkState, setLinkState] = useState("checking");
+	const [password, setPassword] = useState("");
+	const [confirmPassword, setConfirmPassword] = useState("");
+	const [passwordError, setPasswordError] = useState("");
+	const [error, setError] = useState("");
+	const [loading, setLoading] = useState(false);
+	const [done, setDone] = useState(false);
+	const strength = getPasswordStrength(password);
+
+	useEffect(() => {
+		let cancelled = false;
+
+		void (async () => {
+			try {
+				const res = await fetch(
+					`/api/auth/reset-password?token=${encodeURIComponent(token)}`,
+				);
+				if (!cancelled) {
+					setLinkState(res.ok ? "ready" : "invalid");
+				}
+			} catch {
+				if (!cancelled) setLinkState("error");
+			}
+		})();
+
+		return () => {
+			cancelled = true;
+		};
+	}, [token]);
+
+	async function handleSubmit(e) {
+		e.preventDefault();
+		setError("");
+
+		const pwdErr = validatePassword(password);
+		if (pwdErr) {
+			setPasswordError(pwdErr);
+			return;
+		}
+
+		if (password !== confirmPassword) {
+			setPasswordError("Passwords do not match.");
+			return;
+		}
+
+		setPasswordError("");
+		setLoading(true);
+
+		try {
+			let res = await postReset(await getCsrfToken());
+
+			if (res.status === 401) {
+				clearCsrfToken();
+				res = await postReset(await getCsrfToken());
+			}
+
+			if (!res.ok) {
+				const body = await res.json().catch(() => ({}));
+				setError(body.message || "Reset failed. Try again.");
+				setLoading(false);
+				return;
+			}
+
+			setDone(true);
+			setLoading(false);
+		} catch {
+			setError("Could not reach the server. Try again.");
+			setLoading(false);
+		}
+	}
+
+	async function postReset(csrfToken) {
+		return await fetch("/api/auth/reset-password", {
+			method: "POST",
+			headers: {
+				"Content-Type": "application/json",
+				"X-CSRF-Token": csrfToken,
+			},
+			body: JSON.stringify({ token, password }),
+		});
+	}
+
+	return (
+		<div className="quark-auth-layout">
+			{/* Authority / branding panel */}
+			<div className="quark-auth-brand">
+				<Link href="/" aria-label="Go to home">
+					<QuarkLogo size={64} className="mb-8" />
+				</Link>
+				<p className="text-xs uppercase tracking-widest text-text-faint mb-3">
+					Account recovery
+				</p>
+				<h2 className="text-3xl font-bold text-text leading-tight mb-4">
+					Choose a new password.
+				</h2>
+				<p className="text-sm text-text-muted leading-relaxed">
+					Once set, every existing session is signed out — including any session
+					the old password was signed in from.
+				</p>
+			</div>
+
+			{/* Form panel */}
+			<div className="quark-auth-form">
+				{/* Mobile-only logo */}
+				<div className="flex md:hidden mb-8">
+					<Link href="/" aria-label="Go to home">
+						<QuarkLogo size={44} />
+					</Link>
+				</div>
+
+				<div className="quark-auth-panel w-full max-w-sm">
+					<div className="mb-8">
+						<h1 className="text-2xl font-bold tracking-tight text-text">
+							Reset password
+						</h1>
+					</div>
+
+					<ErrorBanner message={error} />
+
+					{linkState === "checking" ? (
+						<p className="text-sm text-text-muted leading-relaxed mb-8">
+							Checking your link…
+						</p>
+					) : null}
+
+					{linkState === "invalid" || linkState === "error" ? (
+						<>
+							<p className="text-sm text-text-muted leading-relaxed mb-8">
+								This reset link is invalid or has expired. Request a new one
+								from the forgot-password page.
+							</p>
+							<Link
+								href="/auth/forgot-password"
+								className="text-xs text-primary hover:opacity-75 transition-opacity duration-200 linear uppercase tracking-widest"
+							>
+								Request a new link
+							</Link>
+						</>
+					) : null}
+
+					{linkState === "ready" && !done ? (
+						<form onSubmit={handleSubmit} className="space-y-5">
+							<div className="space-y-2">
+								<Label htmlFor="password">New password</Label>
+								<PasswordInput
+									id="password"
+									autoComplete="new-password"
+									required
+									value={password}
+									onChange={(e) => {
+										setPassword(e.target.value);
+										if (passwordError)
+											setPasswordError(validatePassword(e.target.value));
+									}}
+								/>
+								{password && (
+									<div className="space-y-1">
+										<div className="flex gap-0.5">
+											{[1, 2, 3, 4].map((seg) => (
+												<div
+													key={seg}
+													className={`h-0.5 flex-1 transition-colors duration-200 linear ${strength >= seg ? STRENGTH_COLORS[strength] : "bg-border"}`}
+												/>
+											))}
+										</div>
+										<p className="text-xs text-text-faint uppercase tracking-widest">
+											{STRENGTH_LABELS[strength]}
+										</p>
+									</div>
+								)}
+							</div>
+
+							<div className="space-y-2">
+								<Label htmlFor="confirm-password">Confirm new password</Label>
+								<PasswordInput
+									id="confirm-password"
+									autoComplete="new-password"
+									required
+									value={confirmPassword}
+									onChange={(e) => {
+										setConfirmPassword(e.target.value);
+										if (passwordError) setPasswordError("");
+									}}
+								/>
+								{passwordError ? (
+									<p className="text-xs text-danger uppercase tracking-widest">
+										{passwordError}
+									</p>
+								) : null}
+							</div>
+
+							<Button
+								type="submit"
+								variant="primary"
+								className="w-full mt-2"
+								disabled={loading}
+							>
+								{loading ? "Resetting…" : "Set new password →"}
+							</Button>
+						</form>
+					) : null}
+
+					{done ? (
+						<>
+							<p
+								role="status"
+								className="text-sm text-text-muted leading-relaxed mb-8"
+							>
+								Your password has been updated. All previous sessions have been
+								signed out.
+							</p>
+							<Link
+								href="/auth/signin"
+								className="text-xs text-primary hover:opacity-75 transition-opacity duration-200 linear uppercase tracking-widest"
+							>
+								Sign in with your new password →
+							</Link>
+						</>
+					) : null}
+				</div>
+			</div>
+		</div>
+	);
+}

package/templates/base-project/apps/web/src/app/auth/reset-password/page.js

@@ -0,0 +1,9 @@
+import ResetPasswordPageClient from "./ResetPasswordPageClient";
+
+export const metadata = {
+	title: "Reset Password",
+};
+
+export default function ResetPasswordPage() {
+	return <ResetPasswordPageClient />;
+}

package/templates/base-project/apps/web/src/app/auth/signin/SignInPageClient.js

@@ -37,6 +37,7 @@ function SignInForm({ allowSignup }) {
 	const searchParams = useSearchParams();
 	const callbackUrl = searchParams.get("callbackUrl") || "/";
 	const errorCode = searchParams.get("error");
+	const verified = searchParams.get("verified");
 
 	const [email, setEmail] = useState("");
 	const [password, setPassword] = useState("");
@@ -46,6 +47,18 @@ function SignInForm({ allowSignup }) {
 	const [error, setError] = useState(
 		errorCode ? (ERROR_MESSAGES[errorCode] ?? ERROR_MESSAGES.Default) : "",
 	);
+	// `/api/auth/verify-email` redirects here with ?verified=1|invalid|error.
+	// A notice is the difference between "why can I sign in now?" and "did my
+	// email even work?" for a user arriving from their mailbox.
+	const [notice] = useState(
+		verified === "1"
+			? "Your email address is verified. You can sign in."
+			: verified === "invalid"
+				? "That verification link is invalid or has expired."
+				: verified === "error"
+					? "Verification failed. Try again from the link in your email."
+					: "",
+	);
 
 	useEffect(() => {
 		let cancelled = false;
@@ -131,6 +144,15 @@ function SignInForm({ allowSignup }) {
 
 					<ErrorBanner message={error} />
 
+					{notice ? (
+						<div
+							role="status"
+							className="border border-success/40 bg-success-muted px-4 py-3 text-sm text-success mb-8"
+						>
+							{notice}
+						</div>
+					) : null}
+
 					<form onSubmit={handleSubmit} className="space-y-5">
 						<div className="space-y-2">
 							<Label htmlFor="email">Email</Label>

package/templates/base-project/apps/web/src/lib/enqueue-email-job.js

@@ -0,0 +1,67 @@
+/**
+ * Queue name and enqueue mechanics shared by every transactional email the web
+ * service sends.
+ *
+ * The queue module is imported dynamically from inside this file, so callers
+ * that import a thin wrapper statically never pull BullMQ into their module
+ * graph. That matters most for `/api/auth/*` routes, which are reachable on the
+ * web service: a module-scope `createQueue` import both loaded BullMQ at
+ * startup and pinned a Redis connection to the web process for as long as the
+ * process lived.
+ *
+ * It also gives each route a static boundary to substitute in tests. `mock.module`
+ * intercepts a dynamic import only when the importing module registered the
+ * mock, so a dynamic import made by the route itself cannot be mocked from the
+ * route's test. A static import of a wrapper module can.
+ *
+ * The queue name is duplicated here rather than imported from `@<scope>/jobs`
+ * on purpose: `jobs` is an optional scaffold package, and importing it from the
+ * web module broke the build of every project that declined it. The
+ * `packages/cli` scaffold-drift test fails when this copy diverges from the
+ * jobs definitions.
+ */
+export const EMAIL_QUEUE = "email-queue";
+
+/**
+ * Loads the queue module on demand.
+ *
+ * Kept as a named binding rather than an inline `import()` so it can be
+ * substituted — see `loadQueue` on {@link enqueueEmailJob}.
+ *
+ * @returns {Promise<typeof import("@usequark/quark-core/queue")>}
+ */
+function loadQueueModule() {
+	return import("@usequark/quark-core/queue");
+}
+
+/**
+ * Enqueues an email job, closing the queue either way.
+ *
+ * @param {string} jobName - Job name from the jobs package (e.g.
+ *   `SEND_WELCOME_EMAIL`). The worker rejects an unknown name, so this is not
+ *   validated client-side — a helper that silently accepted a typo would hide
+ *   the rejection in a log line.
+ * @param {object} data - Job payload, validated by the worker's handler.
+ * @param {() => Promise<{ createQueue: (name: string, options?: object) => object }>} [loadQueue]
+ *   How to obtain the queue module. Defaults to the dynamic import above;
+ *   overridden in tests.
+ * @returns {Promise<void>}
+ * @throws Whatever `createQueue` or `add` throws. The queue is closed either
+ *   way, so a caller that swallows the error still leaves no connection behind.
+ */
+export async function enqueueEmailJob(
+	jobName,
+	data,
+	loadQueue = loadQueueModule,
+) {
+	const { createQueue } = await loadQueue();
+	const queue = createQueue(EMAIL_QUEUE);
+
+	try {
+		await queue.add(jobName, data);
+	} finally {
+		// Never let a failing close mask the enqueue outcome — the caller only
+		// needs to know whether the job reached the queue.
+		await queue.close().catch(() => {});
+	}
+}

package/templates/base-project/apps/web/src/lib/enqueue-reset-password-email.js

@@ -0,0 +1,33 @@
+import { enqueueEmailJob } from "./enqueue-email-job.js";
+
+/**
+ * Job name for the password-reset message.
+ *
+ * Mirrors `JOB_NAMES.SEND_RESET_PASSWORD_EMAIL` in the optional `@<scope>/jobs`
+ * package (see `enqueue-email-job.js` for why it is duplicated). The
+ * `packages/cli` scaffold-drift test fails when the two copies diverge.
+ *
+ * Until this helper existed, no scaffolded route enqueued this job: the worker
+ * handler and the email template shipped, but nothing ever called them. The
+ * forgot-password route is the caller.
+ */
+export const SEND_RESET_PASSWORD_EMAIL = "send-reset-password-email";
+
+/**
+ * Enqueues the password-reset email for a user who requested one.
+ *
+ * @param {string} userId - The user to email. The worker resolves the address
+ *   from this id, so the reset link cannot be sent to an attacker-chosen
+ *   mailbox.
+ * @param {string} resetUrl - Absolute, single-use reset link.
+ * @param {() => Promise<{ createQueue: (name: string, options?: object) => object }>} [loadQueue]
+ *   Queue-module loader, overridden in tests. See {@link enqueueEmailJob}.
+ * @returns {Promise<void>}
+ */
+export async function enqueueResetPasswordEmail(userId, resetUrl, loadQueue) {
+	return enqueueEmailJob(
+		SEND_RESET_PASSWORD_EMAIL,
+		{ userId, resetUrl },
+		loadQueue,
+	);
+}

package/templates/base-project/apps/web/src/lib/enqueue-verification-email.js

@@ -0,0 +1,25 @@
+import { enqueueEmailJob } from "./enqueue-email-job.js";
+
+/**
+ * Job name for the email-verification message.
+ *
+ * Mirrors `JOB_NAMES.SEND_VERIFY_EMAIL` in the optional `@<scope>/jobs`
+ * package (see `enqueue-email-job.js` for why it is duplicated). The
+ * `packages/cli` scaffold-drift test fails when the two copies diverge.
+ */
+export const SEND_VERIFY_EMAIL = "send-verify-email";
+
+/**
+ * Enqueues the verification email a new account needs to confirm its address.
+ *
+ * @param {string} userId - The user whose address is being confirmed. The worker
+ *   resolves the address from this id rather than trusting the caller, so an
+ *   attacker cannot enqueue a verification mail to an address they do not own.
+ * @param {string} verifyUrl - Absolute, single-use confirmation link.
+ * @param {() => Promise<{ createQueue: (name: string, options?: object) => object }>} [loadQueue]
+ *   Queue-module loader, overridden in tests. See {@link enqueueEmailJob}.
+ * @returns {Promise<void>}
+ */
+export async function enqueueVerificationEmail(userId, verifyUrl, loadQueue) {
+	return enqueueEmailJob(SEND_VERIFY_EMAIL, { userId, verifyUrl }, loadQueue);
+}

package/templates/base-project/apps/web/src/lib/enqueue-welcome-email.js

@@ -1,62 +1,27 @@
-/**
- * Queue and job name for the signup welcome email.
- *
- * These mirror `JOB_QUEUES.EMAIL` and `JOB_NAMES.SEND_WELCOME_EMAIL` in the
- * `@<scope>/jobs` package — an *optional* scaffold package. Importing them from
- * there puts `@<scope>/jobs` in the web module graph of every project, and a
- * project that declines `jobs` has no such dependency to resolve: the web app
- * fails to build before any test can run. The strings are duplicated here on
- * purpose; a `packages/cli` test fails when the two copies diverge.
- */
-export const EMAIL_QUEUE = "email-queue";
-export const SEND_WELCOME_EMAIL = "send-welcome-email";
+import { enqueueEmailJob } from "./enqueue-email-job.js";
+
+// Re-exported so callers that already import the welcome helper keep their
+// import site, and so its test still asserts the queue name in one place.
+export { EMAIL_QUEUE } from "./enqueue-email-job.js";
 
 /**
- * Loads the queue module on demand.
- *
- * Kept as a named binding rather than an inline `import()` so it can be
- * substituted — see `loadQueue` on {@link enqueueWelcomeEmail}.
+ * Job name for the signup welcome email.
  *
- * @returns {Promise<typeof import("@usequark/quark-core/queue")>}
+ * Mirrors `JOB_NAMES.SEND_WELCOME_EMAIL` in the optional `@<scope>/jobs`
+ * package (see `enqueue-email-job.js` for why it is duplicated). The
+ * `packages/cli` scaffold-drift test fails when the two copies diverge.
  */
-function loadQueueModule() {
-	return import("@usequark/quark-core/queue");
-}
+export const SEND_WELCOME_EMAIL = "send-welcome-email";
 
 /**
  * Enqueues the post-signup welcome email for a newly created user.
  *
- * This lives in its own module for two reasons.
- *
- * The queue module is imported dynamically from inside this file, so callers
- * that import *this* statically never pull BullMQ into their module graph. That
- * matters most for `/api/auth/register`, which is reachable on the web service:
- * a module-scope `createQueue` import both loaded BullMQ at startup and pinned a
- * Redis connection to the web process for as long as the process lived.
- *
- * It also gives the route a static boundary to substitute in tests. `mock.module`
- * intercepts a dynamic import only when the importing module registered the mock,
- * so a dynamic import made by the route itself cannot be mocked from the route's
- * test. A static import of this module can.
- *
  * @param {string} userId - The user to welcome. The worker rejects a job with
  *   no userId, so this is required rather than defaulted.
  * @param {() => Promise<{ createQueue: (name: string, options?: object) => object }>} [loadQueue]
- *   How to obtain the queue module. Defaults to the dynamic import above;
- *   overridden in tests.
+ *   Queue-module loader, overridden in tests. See {@link enqueueEmailJob}.
  * @returns {Promise<void>}
- * @throws Whatever `createQueue` or `add` throws. The queue is closed either
- *   way, so a caller that swallows the error still leaves no connection behind.
  */
-export async function enqueueWelcomeEmail(userId, loadQueue = loadQueueModule) {
-	const { createQueue } = await loadQueue();
-	const queue = createQueue(EMAIL_QUEUE);
-
-	try {
-		await queue.add(SEND_WELCOME_EMAIL, { userId });
-	} finally {
-		// Never let a failing close mask the enqueue outcome — the caller only
-		// needs to know whether the job reached the queue.
-		await queue.close().catch(() => {});
-	}
+export async function enqueueWelcomeEmail(userId, loadQueue) {
+	return enqueueEmailJob(SEND_WELCOME_EMAIL, { userId }, loadQueue);
 }

package/templates/base-project/apps/web/src/lib/issue-verification-token.js

@@ -0,0 +1,52 @@
+import { generateToken, hashToken } from "@usequark/quark-core/auth";
+import { verificationToken } from "@usequark/quark-db";
+
+/**
+ * Lifetime of a password-reset link.
+ *
+ * An hour is enough for a mail to arrive and a person to act on it, and short
+ * enough that a link found later in a mailbox archive is already dead. The
+ * reset email quotes the same window; changing one without the other would make
+ * the email lie.
+ */
+export const RESET_TOKEN_TTL_MS = 60 * 60 * 1000;
+
+/**
+ * Lifetime of an email-verification link.
+ *
+ * Longer than a reset: an address is confirmed on the user's own schedule, and
+ * nothing is ambiently at risk while the link lives — redeeming it only sets
+ * the verified flag, it does not grant a session.
+ */
+export const VERIFY_TOKEN_TTL_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * Issues a single-use verification token for an identifier and returns the raw
+ * value to embed in the emailed link.
+ *
+ * The stored row holds only the SHA-256 digest (`hashToken`), never the value
+ * the link carries: a leaked database row must not be redeemable. Resolution
+ * hashes the presented token before looking it up, so the two always meet.
+ *
+ * Any outstanding token for the identifier is deleted first. A user who clicks
+ * "resend" twice should not leave two working links behind — the newest request
+ * is the one they are looking at, and an old email in a shared inbox should
+ * stop working the moment a replacement is issued.
+ *
+ * @param {string} identifier - The user's email address (the `VerificationToken`
+ *   identifier column).
+ * @param {number} ttlMs - Token lifetime in milliseconds.
+ * @returns {Promise<string>} The raw token to place in the link. Not stored.
+ */
+export async function issueVerificationToken(identifier, ttlMs) {
+	await verificationToken.deleteByIdentifier(identifier);
+
+	const token = generateToken();
+	await verificationToken.create({
+		identifier,
+		token: hashToken(token),
+		expires: new Date(Date.now() + ttlMs),
+	});
+
+	return token;
+}

package/templates/base-project/apps/web/src/lib/proxy-auth.js

@@ -7,6 +7,13 @@ const STRICT_AUTH_RATE_LIMIT_ROUTES = new Set([
 	// redirects to the sign-in page — nothing to brute force.
 	"/api/auth/callback/credentials",
 	"/api/auth/register",
+	// Password recovery surfaces are credential-adjacent and stay strict:
+	// `forgot-password` is an email-sending surface (5 per 15 minutes per
+	// IP:path stops an attacker from flooding one mailbox), and
+	// `reset-password` is a token-redeeming surface (the same budget limits
+	// grinding through stolen or guessed links).
+	"/api/auth/forgot-password",
+	"/api/auth/reset-password",
 ]);
 
 /**

package/templates/base-project/apps/web/src/lib/send-reset-password-email.js

@@ -0,0 +1,24 @@
+import { getAppUrl } from "@usequark/quark-config";
+import { enqueueResetPasswordEmail } from "./enqueue-reset-password-email.js";
+import {
+	issueVerificationToken,
+	RESET_TOKEN_TTL_MS,
+} from "./issue-verification-token.js";
+
+/**
+ * Issues a password-reset link for an account and enqueues the email that
+ * carries it.
+ *
+ * Kept out of the forgot-password route for the same reason the verification
+ * equivalent is kept out of the register route: one place that defines how the
+ * link is built, and one test for that definition.
+ *
+ * @param {{ id: string, email: string }} account - The account that requested a reset.
+ * @returns {Promise<void>}
+ */
+export async function sendResetPasswordEmail(account) {
+	const token = await issueVerificationToken(account.email, RESET_TOKEN_TTL_MS);
+	const resetUrl = `${getAppUrl()}/auth/reset-password?token=${token}`;
+
+	await enqueueResetPasswordEmail(account.id, resetUrl);
+}

package/templates/base-project/apps/web/src/lib/send-verification-email.js

@@ -0,0 +1,28 @@
+import { getAppUrl } from "@usequark/quark-config";
+import { enqueueVerificationEmail } from "./enqueue-verification-email.js";
+import {
+	issueVerificationToken,
+	VERIFY_TOKEN_TTL_MS,
+} from "./issue-verification-token.js";
+
+/**
+ * Issues a verification link for an account and enqueues the email that carries
+ * it.
+ *
+ * Kept out of the register route so the route reads as "create the user, then
+ * hand off" and so this sequence has one test that does not have to stand up
+ * the whole registration path. The route treats any failure here as
+ * non-fatal — the account exists either way.
+ *
+ * @param {{ id: string, email: string }} account - The freshly created user.
+ * @returns {Promise<void>}
+ */
+export async function sendVerificationEmail(account) {
+	const token = await issueVerificationToken(
+		account.email,
+		VERIFY_TOKEN_TTL_MS,
+	);
+	const verifyUrl = `${getAppUrl()}/api/auth/verify-email?token=${token}`;
+
+	await enqueueVerificationEmail(account.id, verifyUrl);
+}

package/templates/base-project/packages/db/src/queries.js

@@ -197,6 +197,19 @@ export const verificationToken = {
 			where: { identifier, token },
 		});
 	},
+	/**
+	 * Removes every token for an identifier.
+	 *
+	 * A verification or reset flow issues one live token per address: without
+	 * this, requesting a second link leaves the first valid too, so an old email
+	 * keeps working after the user asked for a new one. Called before issuing a
+	 * replacement, and again once a token has been redeemed.
+	 */
+	deleteByIdentifier: (identifier) => {
+		return prisma.verificationToken.deleteMany({
+			where: { identifier },
+		});
+	},
 	deleteExpired: () => {
 		return prisma.verificationToken.deleteMany({
 			where: { expires: { lt: new Date() } },

package/templates/base-project/packages/db/src/schemas.js

@@ -6,14 +6,24 @@ export const userCreateSchema = z.object({
 	image: z.string().url().optional(),
 });
 
+/**
+ * Password rules, shared by every route that sets one.
+ *
+ * Registration and password reset must not drift: a reset that accepts a weaker
+ * password than signup would let a user downgrade their own credential, and the
+ * reverse would lock a legitimate password out of recovery. Composed into
+ * `userRegisterSchema` rather than duplicated, so there is one definition.
+ */
+export const passwordSchema = z
+	.string()
+	.min(8, "Password must be at least 8 characters")
+	.regex(/[A-Z]/, "Password must contain at least one uppercase letter")
+	.regex(/[a-z]/, "Password must contain at least one lowercase letter")
+	.regex(/[0-9]/, "Password must contain at least one number");
+
 export const userRegisterSchema = z.object({
 	email: z.string().email("Invalid email address"),
-	password: z
-		.string()
-		.min(8, "Password must be at least 8 characters")
-		.regex(/[A-Z]/, "Password must contain at least one uppercase letter")
-		.regex(/[a-z]/, "Password must contain at least one lowercase letter")
-		.regex(/[0-9]/, "Password must contain at least one number"),
+	password: passwordSchema,
 	name: z.string().min(2, "Name must be at least 2 characters").optional(),
 });
 

package/templates/jobs/src/definitions.js

@@ -6,6 +6,7 @@ export const JOB_QUEUES = {
 
 export const JOB_NAMES = {
 	SEND_WELCOME_EMAIL: "send-welcome-email",
+	SEND_VERIFY_EMAIL: "send-verify-email",
 	SEND_RESET_PASSWORD_EMAIL: "send-reset-password-email",
 	CLEANUP_ORPHANED_FILES: "cleanup-orphaned-files",
 };

package/templates/worker/src/handlers/email-job-validation.js

@@ -23,6 +23,19 @@ export function requireResetPasswordEmailData(data) {
 	return { userId, resetUrl };
 }
 
+export function requireVerifyEmailData(data) {
+	const userId = data?.userId;
+	const verifyUrl = data?.verifyUrl;
+
+	if (!userId || !verifyUrl) {
+		throw new ValidationError(
+			"userId and verifyUrl are required for SEND_VERIFY_EMAIL job",
+		);
+	}
+
+	return { userId, verifyUrl };
+}
+
 export function requireUserEmailRecord(userId, userRecord) {
 	if (!userRecord?.email) {
 		throw new AppError(

package/templates/worker/src/handlers/email.js

@@ -5,6 +5,7 @@
 
 import { createEmailService } from "@usequark/quark-core/email";
 import {
+	emailVerificationEmail,
 	passwordResetEmail,
 	welcomeEmail,
 } from "@usequark/quark-core/email-templates";
@@ -13,6 +14,7 @@ import { JOB_NAMES } from "@usequark/quark-jobs";
 import {
 	requireResetPasswordEmailData,
 	requireUserEmailRecord,
+	requireVerifyEmailData,
 	requireWelcomeEmailUserId,
 } from "./email-job-validation.js";
 
@@ -94,5 +96,42 @@ export async function handleSendResetPasswordEmail(bullJob, logger) {
 	return { success: true, userId, email: userRecord.email };
 }
 
+/**
+ * Job handler for SEND_VERIFY_EMAIL
+ * @param {import("bullmq").Job} bullJob
+ * @param {import("@usequark/quark-core").Logger} logger
+ */
+export async function handleSendVerificationEmail(bullJob, logger) {
+	const { userId, verifyUrl } = requireVerifyEmailData(bullJob.data);
+
+	logger.info(`Sending email verification for user ${userId}`, {
+		job: JOB_NAMES.SEND_VERIFY_EMAIL,
+		userId,
+	});
+
+	const userRecord = requireUserEmailRecord(
+		userId,
+		await prisma.user.findUnique({
+			where: { id: userId },
+			select: { email: true, name: true },
+		}),
+	);
+
+	const template = emailVerificationEmail({
+		name: userRecord.name,
+		appName: process.env.APP_NAME,
+		verifyUrl,
+	});
+
+	await emailService.sendEmail(
+		userRecord.email,
+		template.subject,
+		template.html,
+		template.text,
+	);
+
+	return { success: true, userId, email: userRecord.email };
+}
+
 // Governance alerts are sent inline by the governance-check handler.
 // No standalone handler needed in Quark.

package/templates/worker/src/handlers/index.js

@@ -7,12 +7,14 @@
 import { JOB_NAMES } from "@usequark/quark-jobs";
 import {
 	handleSendResetPasswordEmail,
+	handleSendVerificationEmail,
 	handleSendWelcomeEmail,
 } from "./email.js";
 import { handleCleanupOrphanedFiles } from "./files.js";
 
 export const jobHandlers = {
 	[JOB_NAMES.SEND_WELCOME_EMAIL]: handleSendWelcomeEmail,
+	[JOB_NAMES.SEND_VERIFY_EMAIL]: handleSendVerificationEmail,
 	[JOB_NAMES.SEND_RESET_PASSWORD_EMAIL]: handleSendResetPasswordEmail,
 	[JOB_NAMES.CLEANUP_ORPHANED_FILES]: handleCleanupOrphanedFiles,
 };