@usequark/quark-create-app 1.25.15 → 1.26.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usequark/quark-create-app",
-  "version": "1.25.15",
+  "version": "1.26.0",
   "description": "CLI to scaffold new Quark projects with Next.js, Prisma, BullMQ, and Railway deployment",
   "keywords": [
     "quark",
@@ -59,9 +59,8 @@
     "sync-templates:check": "node scripts/sync-templates.js --check",
     "regen-migration": "node scripts/regenerate-template-migration.js",
     "smoke:published": "node scripts/smoke-published.js",
-    "test": "node test-cli.js && node --test src/utils.test.js && node --test src/prepare-hooks.test.js && node --test src/scaffold-warning.test.js && node --test src/scaffold-output.test.js && node --test src/scaffold-drift.test.js && node --test src/mobile-template.test.js && node --test src/template-scripts.test.js && node --test src/scaffold-guards.test.js && node --test src/template-config.test.js && node --test src/worker-dockerfile.test.js && node --test src/dependabot-config.test.js && node --test 'src/deploy/**/*.test.js' && node --test --test-concurrency=1 'src/deploy/**/*.integration.test.js'",
+    "test": "node test-cli.js && node --test src/utils.test.js && node --test src/prepare-hooks.test.js && node --test src/scaffold-warning.test.js && node --test src/scaffold-output.test.js && node --test src/scaffold-drift.test.js && node --test src/mobile-template.test.js && node --test src/template-scripts.test.js && node --test src/scaffold-guards.test.js && node --test src/template-config.test.js && node --test src/worker-dockerfile.test.js && node --test src/dependabot-config.test.js && node --test 'src/deploy/**/*.test.js' && node --test --test-concurrency=1 'src/deploy/**/*.integration.test.js' && node --test test-flags.js",
     "test:build": "node test-build.js",
-    "test:e2e": "node test-e2e.js",
     "test:e2e:full": "node test-e2e-full.js",
     "test:integration": "node test-integration.js",
     "test:flags": "node --test test-flags.js",

package/src/index.js

@@ -705,8 +705,11 @@ program
 						`          as its own repository, or\n` +
 						`        • scaffold into a temporary folder and move the files to\n` +
 						`          the repository root before the first commit.\n\n` +
-						`      Git initialization will be skipped to avoid creating a\n` +
-						`      nested repository.\n\n` +
+						`      Git initialization ${
+							process.env.QUARK_FORCE_GIT_INIT === "true"
+								? "will run anyway (QUARK_FORCE_GIT_INIT=true)."
+								: "will be skipped to avoid creating a\n      nested repository."
+						}\n\n` +
 						`      GitHub only runs workflows stored at the repository root, so\n` +
 						`      <project>/.github/workflows/*.yml will be ignored by GitHub\n` +
 						`      Actions.\n`,
@@ -1577,7 +1580,11 @@ STORAGE_PROVIDER=local
 			// Step 11: Initialize git repository
 			if (process.env.QUARK_SKIP_GIT_INIT === "true") {
 				console.log(chalk.dim("\n  · Skipping git initialization"));
-			} else if (enclosingRepo) {
+			} else if (enclosingRepo && process.env.QUARK_FORCE_GIT_INIT !== "true") {
+				// `initializeGit()` also checks QUARK_FORCE_GIT_INIT internally,
+				// but it is only reached in the else branch below — short-
+				// circuiting here on `enclosingRepo` alone made the documented
+				// force flag a no-op.
 				console.log(
 					chalk.dim(
 						"\n  · Skipping git initialization (inside an existing repository)",

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 />;
 }