@usequark/quark-create-app 1.26.0 → 1.27.1

package/README.md

@@ -48,7 +48,7 @@ npx @usequark/quark-create-app@latest my-app
 npx @usequark/quark-create-app add jobs
 
 # Print an embedded skill for a feature
-npx @usequark/quark-create-app skill bookings
+npx @usequark/quark-create-app skill model
 
 # Update Quark packages in an existing project
 npx @usequark/quark-create-app update
@@ -95,7 +95,7 @@ npx @usequark/quark-create-app@latest my-app --no-prompts
 
 ### Packages
 
-Specify which optional packages to include (default: `ui,jobs`; valid: `ui`, `jobs`):
+Specify which optional packages to include (default: `ui,jobs`; valid: `ui`, `jobs`, `pwa` — `mobile` is added post-creation via `quark add mobile`):
 
 ```bash
 # Only include UI package
@@ -131,16 +131,13 @@ npx @usequark/quark-create-app@latest my-app --no-prompts --signup disabled
 Print an embedded skill for a feature:
 
 ```bash
-# Print the bookings skill
-npx @usequark/quark-create-app@latest skill bookings
-
 # Print a core skill (model, endpoint, dashboard)
 npx @usequark/quark-create-app@latest skill model
 npx @usequark/quark-create-app@latest skill endpoint
 npx @usequark/quark-create-app@latest skill dashboard
 ```
 
-Available skills: `model`, `endpoint`, `dashboard`, `bookings`, `crm`, `cms`, `ai`.
+Available skills: `model`, `endpoint`, `dashboard` (core workflows), plus the embedded domain skills shipped with every project (`payment`, `ecommerce` incl. catalog/cart/checkout, `i18n`). Domain verticals (`bookings`, `crm`, `cms`, `ai`) are built on demand via those workflows, not printed as named skills.
 
 ### Skip Installation Steps
 
@@ -189,8 +186,9 @@ npx @usequark/quark-create-app@latest my-app \
 # Lightweight template checks
 pnpm test
 
-# E2E scaffold simulation
-pnpm test:e2e
+# Full lifecycle E2E (scaffold -> build -> Docker -> migrate -> run). Phase 3
+# runs `pnpm build`, so a scaffolded import that does not compile fails here.
+pnpm test:e2e:full
 
 # Full build verification (opt-in)
 QUARK_CLI_BUILD_TEST=1 pnpm test:build

package/package.json

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

package/src/index.js

@@ -1363,6 +1363,13 @@ STORAGE_PROVIDER=local
 # RATE_LIMIT_WINDOW_MS=900000  # Window in ms (default: 15 minutes)
 # API_BODY_SIZE_LIMIT=2097152  # 2MB (default)
 # UPLOAD_SIZE_LIMIT=10485760   # 10MB proxy-level limit (default)
+# Rate-limit buckets key on <client-ip>:<path>, the client IP taken from the
+# proxy headers (left-most x-forwarded-for, then x-real-ip). Default (unset)
+# trusts those headers - the right choice behind a reverse proxy (Railway/
+# Docker/nginx) that overwrites them. Set to false when the app is exposed
+# directly, so a spoofed header cannot earn a fresh bucket; every client then
+# shares one bucket per route.
+# TRUST_PROXY_HEADERS=true
 
 # --- Logging & Cache ---
 # LOG_LEVEL=debug              # debug, info, warn, error (default: debug dev, info prod)
@@ -1936,6 +1943,58 @@ async function compareScaffoldManagedFiles(expectedDir, projectDir) {
 	};
 }
 
+/**
+ * Apply the mobile-specific edits `add mobile` makes to scaffold-managed ROOT
+ * files.
+ *
+ * `mobile` is a post-creation-only feature: `create` rejects it, so the
+ * reference scaffold `update --scaffold-check` builds can never carry these
+ * edits. Replaying them on the reference when the project has mobile installed
+ * scopes the byte comparison by installed feature instead of reporting the
+ * expected `EXPO_PUBLIC_API_URL` block as drift.
+ *
+ * This does not weaken drift detection: the edits are constants, so tampering
+ * with — or deleting — the mobile block in a project still differs from the
+ * reference and is still reported.
+ *
+ * Idempotent, and only writes a file when it actually changes it.
+ *
+ * @param {string} projectDir
+ */
+async function applyMobileScaffoldEdits(projectDir) {
+	const envExamplePath = path.join(projectDir, ".env.example");
+	if (await fs.pathExists(envExamplePath)) {
+		const envContent = await fs.readFile(envExamplePath, "utf-8");
+		if (!envContent.includes("EXPO_PUBLIC_API_URL")) {
+			await fs.writeFile(
+				envExamplePath,
+				`${envContent}\n# --- Mobile App ---\nEXPO_PUBLIC_API_URL=http://localhost:3000\n`,
+			);
+		}
+	}
+
+	const rootPkgPath = path.join(projectDir, "package.json");
+	if (!(await fs.pathExists(rootPkgPath))) return;
+
+	const scope = await detectProjectScope(projectDir);
+	if (!scope) return;
+
+	const rootPkg = await fs.readJSON(rootPkgPath);
+	rootPkg.scripts = rootPkg.scripts || {};
+	let changed = false;
+	if (!rootPkg.scripts["dev:mobile"]) {
+		rootPkg.scripts["dev:mobile"] = `pnpm --filter @${scope}/mobile start`;
+		changed = true;
+	}
+	if (!rootPkg.scripts["build:mobile"]) {
+		rootPkg.scripts["build:mobile"] = `pnpm --filter @${scope}/mobile export`;
+		changed = true;
+	}
+	if (changed) {
+		await fs.writeFile(rootPkgPath, `${JSON.stringify(rootPkg, null, "\t")}\n`);
+	}
+}
+
 async function createReferenceScaffold(projectDir, quarkLink) {
 	const projectName = quarkLink.projectName || path.basename(projectDir);
 	const linkedFeatures = resolveFeatureSelection(
@@ -2023,9 +2082,19 @@ async function createReferenceScaffold(projectDir, quarkLink) {
 		);
 	}
 
+	const expectedDir = path.join(tempRoot, projectName);
+
+	// `mobile` is post-creation only, so the subprocess above can never build its
+	// root edits (see scaffoldFeatures). Replay them onto the reference when the
+	// project has mobile installed so the mobile block reads as expected, not as
+	// drift.
+	if (comparisonFeatures.includes("mobile")) {
+		await applyMobileScaffoldEdits(expectedDir);
+	}
+
 	return {
 		tempRoot,
-		expectedDir: path.join(tempRoot, projectName),
+		expectedDir,
 		linkedFeatures,
 		detectedFeatures,
 		comparisonFeatures,
@@ -2390,35 +2459,11 @@ program
 							scope,
 						);
 
-						// Add EXPO_PUBLIC_API_URL to .env.example
-						const envExamplePath = path.join(projectDir, ".env.example");
-						if (await fs.pathExists(envExamplePath)) {
-							let envContent = await fs.readFile(envExamplePath, "utf-8");
-							if (!envContent.includes("EXPO_PUBLIC_API_URL")) {
-								envContent +=
-									"\n# --- Mobile App ---\nEXPO_PUBLIC_API_URL=http://localhost:3000\n";
-								await fs.writeFile(envExamplePath, envContent);
-							}
-						}
-
-						// Add mobile scripts to root package.json
-						const rootPkgPath = path.join(projectDir, "package.json");
-						if (await fs.pathExists(rootPkgPath)) {
-							const rootPkg = await fs.readJSON(rootPkgPath);
-							rootPkg.scripts = rootPkg.scripts || {};
-							if (!rootPkg.scripts["dev:mobile"]) {
-								rootPkg.scripts["dev:mobile"] =
-									`pnpm --filter @${scope}/mobile start`;
-							}
-							if (!rootPkg.scripts["build:mobile"]) {
-								rootPkg.scripts["build:mobile"] =
-									`pnpm --filter @${scope}/mobile export`;
-							}
-							await fs.writeFile(
-								rootPkgPath,
-								`${JSON.stringify(rootPkg, null, "\t")}\n`,
-							);
-						}
+						// Mobile-specific root edits (`.env.example` +
+						// dev:mobile/build:mobile scripts). Shared with the reference
+						// scaffold so `update --scaffold-check` can reproduce them —
+						// see applyMobileScaffoldEdits.
+						await applyMobileScaffoldEdits(projectDir);
 
 						console.log(
 							chalk.green("    ✓ Mobile app scaffolded (apps/mobile)"),

package/templates/base-project/apps/web/.env.example

@@ -102,6 +102,16 @@ ADMIN_PASSWORD=SET_ME
 # Leave unset in development - the endpoint is unprotected by default.
 # METRICS_TOKEN=replace_with_a_long_random_secret
 
+# --- Rate Limiting & Security ---
+# Rate-limit buckets are keyed on the client IP taken from the proxy headers
+# (left-most x-forwarded-for, then x-real-ip). Proxy headers are client-supplied
+# and only an identity when a reverse proxy overwrites them on every request.
+# Default (unset) trusts them - correct behind Railway/Docker/nginx.
+# Set to false when the app is reachable directly: the headers are then ignored
+# and every client shares one bucket per route, so a spoofed x-forwarded-for
+# cannot earn a fresh bucket. Boolean-like: true/false/1/0/yes/no/on/off.
+# TRUST_PROXY_HEADERS=true
+
 # --- File Storage ---
 # Default: local filesystem (./uploads). No further config needed for development.
 STORAGE_PROVIDER=local

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

@@ -5,6 +5,8 @@ import { user } from "@usequark/quark-db";
 import { importJWK, jwtVerify } from "jose";
 import { NextResponse } from "next/server";
 import { z } from "zod";
+import { isEmailVerificationRequired } from "../../../../lib/auth-email-verification";
+import { isEmailVerified } from "../../../../lib/email-verified";
 import { issueTokenPair } from "../../../../lib/jwt";
 import { handleError } from "../../error-handler";
 
@@ -122,6 +124,28 @@ export async function POST(request) {
 			);
 		}
 
+		// An unverified address proves nothing about who controls the inbox, and
+		// this route creates the account on first sight — so without this check the
+		// confirmation that is supposed to establish ownership of the address is
+		// the attacker's to skip rather than the victim's to perform.
+		//
+		// It sits after the missing-email `400` on purpose, matching the Google
+		// route's ordering: that response describes the shape of the token rather
+		// than reporting that the token was refused. What matters for security is
+		// the position relative to the database: the check lands before
+		// `findByEmail`, so an unverified address can never become a registration
+		// or existence oracle. Governed by `REQUIRE_EMAIL_VERIFICATION` like every
+		// other sign-in path — `false` restores the pre-gate behaviour.
+		if (
+			isEmailVerificationRequired() &&
+			!isEmailVerified(payload.email_verified)
+		) {
+			return NextResponse.json(
+				{ message: "Invalid Apple token" },
+				{ status: 401 },
+			);
+		}
+
 		// Find or create user
 		let existingUser = await user.findByEmail(appleEmail);
 		if (!existingUser) {

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

@@ -6,6 +6,7 @@ import { validateBody } from "@usequark/quark-core/core";
 import { user } from "@usequark/quark-db";
 import { NextResponse } from "next/server";
 import { z } from "zod";
+import { isEmailVerificationRequired } from "../../../../lib/auth-email-verification";
 import { isEmailVerified } from "../../../../lib/email-verified";
 import { issueTokenPair } from "../../../../lib/jwt";
 import { handleError } from "../../error-handler";
@@ -85,7 +86,10 @@ export async function POST(request) {
 		// read for what it is. What matters for security is the position relative
 		// to the database: both checks land before `findByEmail`, so an unverified
 		// address can never become a registration or existence oracle.
-		if (!isEmailVerified(tokenInfo.email_verified)) {
+		if (
+			isEmailVerificationRequired() &&
+			!isEmailVerified(tokenInfo.email_verified)
+		) {
 			return NextResponse.json(
 				{ message: "Invalid Google token" },
 				{ status: 401 },

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

@@ -1,4 +1,5 @@
 import { createLogger, validateBody } from "@usequark/quark-core/core";
+import { user as userQueries } from "@usequark/quark-db";
 import { NextResponse } from "next/server";
 import { z } from "zod";
 import { issueTokenPair, verifyMobileToken } from "../../../../lib/jwt";
@@ -10,9 +11,29 @@ const refreshRequestSchema = z.object({
 	refreshToken: z.string().min(1),
 });
 
+/**
+ * The one response every refused refresh gets.
+ *
+ * A deleted account, a password reset, a forged signature and an expired token
+ * are indistinguishable to the caller: they share a status and a body, so a
+ * probing client cannot learn which check failed.
+ */
+function invalidRefreshToken() {
+	return NextResponse.json(
+		{ message: "Invalid or expired refresh token" },
+		{ status: 401 },
+	);
+}
+
 /**
  * POST /api/auth/refresh
  * Exchange a refresh token for a new access token.
+ *
+ * A refresh token lives for 30 days, so the identity it was minted with cannot
+ * be trusted for that long. This re-reads the current id, email, name and role
+ * from the user's row on every exchange — the same revocation contract
+ * `validateSessionToken` applies to web sessions — and refuses the exchange
+ * when the account is gone or its password changed after the token was issued.
  */
 export async function POST(request) {
 	try {
@@ -21,10 +42,7 @@ export async function POST(request) {
 		const payload = await verifyMobileToken(refreshToken);
 		if (!payload) {
 			logger.warn("Invalid refresh token");
-			return NextResponse.json(
-				{ message: "Invalid or expired refresh token" },
-				{ status: 401 },
-			);
+			return invalidRefreshToken();
 		}
 
 		if (payload.type !== "refresh") {
@@ -34,11 +52,42 @@ export async function POST(request) {
 			);
 		}
 
+		// A genuine refresh token always carries `sub`; refuse anything else
+		// rather than handing `undefined` to the query layer.
+		if (typeof payload.sub !== "string" || payload.sub.length === 0) {
+			logger.warn("Refresh token has no subject");
+			return invalidRefreshToken();
+		}
+
+		const account = await userQueries.findById(payload.sub);
+		if (!account) {
+			// Deleted (or otherwise removed) between issue and exchange. Without
+			// this read the route would keep minting access tokens for a ghost.
+			logger.warn("Refresh token for an account that no longer exists");
+			return invalidRefreshToken();
+		}
+
+		// Mirrors `validateSessionToken`: a password reset stamps
+		// `passwordChangedAt`, and any token issued before that instant is dead.
+		// `iat` is whole seconds; comparing against the millisecond stamp as a
+		// fraction keeps a change in the same second from leaking a token.
+		if (
+			account.passwordChangedAt &&
+			typeof payload.iat === "number" &&
+			account.passwordChangedAt.getTime() / 1000 > payload.iat
+		) {
+			logger.warn("Refresh token issued before the password changed");
+			return invalidRefreshToken();
+		}
+
+		// The claims come from the row, never from the token: a 30-day-old
+		// `role` (or any stale profile field) must not be re-stamped onto a fresh
+		// access token.
 		const { token } = await issueTokenPair({
-			id: payload.sub,
-			email: payload.email,
-			name: payload.name,
-			role: payload.role,
+			id: account.id,
+			email: account.email,
+			name: account.name,
+			role: account.role,
 		});
 
 		return NextResponse.json({ token });

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

@@ -84,10 +84,11 @@ export const POST = withCsrfProtection(async (request) => {
 		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.
+			// Stamping the change is what reaches every live session even though
+			// both are self-contained tokens: `validateSessionToken` refuses a web
+			// JWT issued before this instant, and `POST /api/auth/refresh` refuses
+			// a mobile refresh token issued before it — so a password known to an
+			// attacker stops working the moment it is replaced.
 			passwordChangedAt: new Date(),
 		});
 

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

@@ -0,0 +1,5 @@
+import { loadConfig } from "@usequark/quark-config";
+
+export function isEmailVerificationRequired() {
+	return loadConfig().auth.requireEmailVerification;
+}

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

@@ -7,6 +7,7 @@ import NextAuth from "next-auth";
 import CredentialsProvider from "next-auth/providers/credentials";
 import GithubProvider from "next-auth/providers/github";
 import GoogleProvider from "next-auth/providers/google";
+import { isEmailVerificationRequired } from "./auth-email-verification";
 import { isEmailVerified } from "./email-verified";
 
 const logger = createLogger({ name: "auth" });
@@ -65,8 +66,10 @@ const providers = [
 				return null;
 			}
 
+			let existingUser;
+
 			try {
-				const existingUser = await userQueries.findByEmail(credentials.email);
+				existingUser = await userQueries.findByEmail(credentials.email);
 
 				if (!existingUser?.password) {
 					return null;
@@ -80,14 +83,6 @@ const providers = [
 				if (!isValid) {
 					return null;
 				}
-
-				return {
-					id: existingUser.id,
-					email: existingUser.email,
-					name: existingUser.name,
-					image: existingUser.image,
-					role: existingUser.role,
-				};
 			} catch (err) {
 				// Re-throw if the database is unreachable so Auth.js surfaces a server error
 				// rather than "Invalid credentials", which misleads both user and developer.
@@ -109,6 +104,29 @@ const providers = [
 				});
 				return null;
 			}
+
+			// Deliberately after the try/catch above. The verification refusal is a
+			// decision, not a failure: leaving it outside means the fail-closed
+			// handler cannot turn it into a bare `null` that Auth.js would report as
+			// "Invalid credentials". It throws the same `OAUTH_EMAIL_NOT_VERIFIED`
+			// error the OAuth path does, so the operator sees one reason, with one
+			// code, whichever provider the sign-in came through — and, as there, a
+			// missing or unset `emailVerified` reads as unverified.
+			if (isEmailVerificationRequired() && !existingUser.emailVerified) {
+				throw new AppError(
+					"Credentials sign-in refused: the email address is not verified",
+					401,
+					"OAUTH_EMAIL_NOT_VERIFIED",
+				);
+			}
+
+			return {
+				id: existingUser.id,
+				email: existingUser.email,
+				name: existingUser.name,
+				image: existingUser.image,
+				role: existingUser.role,
+			};
 		},
 	}),
 ];
@@ -142,7 +160,10 @@ if (process.env.GOOGLE_CLIENT_ID && process.env.GOOGLE_CLIENT_SECRET) {
 			// why in the one place an operator can read it, and lands in the same
 			// catch: no session, no user row, redirect back to the sign-in page.
 			profile: (profile) => {
-				if (!isEmailVerified(profile.email_verified)) {
+				if (
+					isEmailVerificationRequired() &&
+					!isEmailVerified(profile.email_verified)
+				) {
 					throw new AppError(
 						"Google sign-in refused: the account's email address is not verified",
 						401,
@@ -216,6 +237,13 @@ async function validateSessionToken(token) {
 
 export function getAuthOptions() {
 	return createAuthConfig({
+		// The adapter is load-bearing even though sessions are JWT (see
+		// `session.strategy` below): it persists the `Account` rows that link
+		// OAuth identities to users — the adapter reads and writes them, and
+		// `account.findByUserIdAndProvider` is covered in `packages/db`. Do
+		// not remove it. The `Session` model queries (`session.*` in
+		// `packages/db/src/queries.js`) are the opposite: app-owned helpers the
+		// JWT strategy never populates.
 		adapter: PrismaAdapter(prisma),
 		providers: providers,
 		logger: {

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

@@ -93,23 +93,64 @@ export async function getRateLimiter() {
 	return rateLimiterPromise;
 }
 
+/**
+ * Boolean-like values that disable trusting proxy headers. Mirrors the
+ * "explicit false wins" convention used by `AUTH_ALLOW_SIGNUP` and
+ * `DB_INSTRUMENTATION`, so operators don't have to learn a new dialect.
+ */
+const PROXY_HEADERS_FALSY_VALUES = new Set(["false", "0", "no", "off"]);
+
+/**
+ * Whether the client-supplied proxy headers (`x-forwarded-for`, `x-real-ip`)
+ * may be trusted to identify the client.
+ *
+ * Default `true`: the shipped behaviour. The app assumes it sits behind a
+ * reverse proxy (Railway, Docker, nginx) that overwrites these headers on
+ * every request, so the left-most `x-forwarded-for` entry is treated as the
+ * client IP.
+ *
+ * Set `TRUST_PROXY_HEADERS=false` when the app is reachable directly (no
+ * proxy rewriting the header on the way in). The headers are then ignored and
+ * every client keys on the literal "unknown". Because the bucket key is
+ * `${ip}:${path}`, that means one bucket shared by every client of a route —
+ * not one bucket across all routes. A header a client can set is not an
+ * identity, so this is what stops a spoofed `x-forwarded-for` from buying a
+ * fresh bucket per request. The trade-off is the reverse of the default: one
+ * client can now exhaust the shared bucket for the route it floods, which is
+ * why the default keeps trusting the headers.
+ *
+ * Read lazily (per request) rather than at module load: tests flip it and a
+ * value set after import still takes effect. Only explicit false-like values
+ * disable trusting; unset, empty, "true", or a typo all keep the default.
+ *
+ * @returns {boolean}
+ */
+export function shouldTrustProxyHeaders() {
+	const raw = process.env.TRUST_PROXY_HEADERS?.trim().toLowerCase();
+	return !(raw && PROXY_HEADERS_FALSY_VALUES.has(raw));
+}
+
 /**
  * Resolve the client IP for rate-limit keying.
  *
  * `NextRequest.ip` was removed in Next 15, so `request.ip` is always
- * `undefined` here and every caller collapsed onto the literal key
- * "unknown" — one shared bucket for the whole server. That let a single
- * burst of 5 credential posts (the `auth` bucket) lock out sign-in for
- * everyone for 15 minutes.
+ * `undefined` here and every caller would key on the literal "unknown" — one
+ * bucket shared by every client of a route (the bucket key is `${ip}:${path}`).
+ * That is what made one burst of 5 credential posts lock out sign-in for
+ * everyone for 15 minutes, which is why this reads the proxy headers instead.
  *
- * Trust `x-forwarded-for`/`x-real-ip` only when you are actually behind a
- * reverse proxy (Railway, Docker, nginx) that overwrites them; otherwise a
- * client can spoof them to evade the limiter.
+ * When `TRUST_PROXY_HEADERS` is enabled (the default) the left-most
+ * `x-forwarded-for` entry is used, falling back to `x-real-ip`; both are
+ * client-supplied unless a reverse proxy overwrites them, which is the
+ * assumption the default bakes in (see `shouldTrustProxyHeaders`). With the
+ * flag off both headers are ignored and every request resolves to "unknown".
  *
  * @param {import("next/server").NextRequest} request
  * @returns {string}
  */
 function getClientIp(request) {
+	if (!shouldTrustProxyHeaders()) return "unknown";
+
 	const forwardedFor = request.headers.get("x-forwarded-for");
 	if (forwardedFor) {
 		// Left-most entry is the originating client; later entries are proxies.

package/templates/base-project/packages/db/prisma/schema.prisma

@@ -112,8 +112,13 @@ model Job {
   createdAt DateTime  @default(now())
   updatedAt DateTime  @updatedAt
 
-  // (status, runAt) serves status-only queries through its leftmost prefix;
-  // single-column [status] and [runAt] indexes were removed as redundant.
+  // (status, runAt) serves status-only and (status, runAt) queries
+  // through its leftmost prefix. It does not index runAt alone: a
+  // runAt-only range query cannot use it, so add a single-column
+  // [runAt] index if such a query appears. The shipped code has none
+  // (BullMQ schedules in Redis; this model is an audit trail), so the
+  // single-column [status] and [runAt] indexes were redundant for the
+  // query patterns in use and were removed.
   @@index([queue])
   @@index([status, runAt])
   @@index([createdAt])

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

@@ -139,6 +139,12 @@ export const account = {
 };
 
 // Session queries (NextAuth)
+//
+// App-owned helpers, not Auth.js storage: the scaffold pins
+// `session.strategy: "jwt"` (see `apps/web/src/lib/auth.js`), under which
+// Auth.js neither reads nor writes session rows — revocation is enforced by
+// `validateSessionToken` re-reading the user row instead. Kept for apps that
+// need server-side session bookkeeping of their own.
 export const session = {
 	findByToken: (sessionToken) => {
 		return prisma.session.findUnique({

package/templates/config/src/environment.js

@@ -34,6 +34,7 @@
  * @property {boolean} security.trustProxy - Trust proxy headers
  * @property {Object} auth - Authentication configuration
  * @property {boolean} auth.allowSignup - Allow public self-service signup
+ * @property {boolean} auth.requireEmailVerification - Require verified email for sign-in
  * @property {Object} features - Feature flags
  * @property {boolean} features.debugRoutes - Enable debug endpoints
  * @property {boolean} features.seedOnStart - Auto-seed database on startup
@@ -76,6 +77,7 @@ const ENVIRONMENT_CONFIGS = {
 		},
 		auth: {
 			allowSignup: true,
+			requireEmailVerification: true,
 		},
 		features: {
 			debugRoutes: true,
@@ -118,6 +120,7 @@ const ENVIRONMENT_CONFIGS = {
 		},
 		auth: {
 			allowSignup: true,
+			requireEmailVerification: true,
 		},
 		features: {
 			debugRoutes: true,
@@ -160,6 +163,7 @@ const ENVIRONMENT_CONFIGS = {
 		},
 		auth: {
 			allowSignup: true,
+			requireEmailVerification: true,
 		},
 		features: {
 			debugRoutes: false,
@@ -202,6 +206,7 @@ const ENVIRONMENT_CONFIGS = {
 		},
 		auth: {
 			allowSignup: true,
+			requireEmailVerification: true,
 		},
 		features: {
 			debugRoutes: false,

package/templates/config/src/load-config.js

@@ -121,6 +121,14 @@ function buildEnvOverrides(_envConfig) {
 			overrides.auth = { ...overrides.auth, allowSignup };
 		}
 	}
+	if (process.env.REQUIRE_EMAIL_VERIFICATION) {
+		const requireEmailVerification = parseBooleanEnv(
+			process.env.REQUIRE_EMAIL_VERIFICATION,
+		);
+		if (requireEmailVerification !== undefined) {
+			overrides.auth = { ...overrides.auth, requireEmailVerification };
+		}
+	}
 
 	// Database pool
 	if (process.env.DB_POOL_MAX) {

package/templates/config/src/validate-env.js

@@ -110,6 +110,8 @@ const ENV_DESCRIPTIONS = {
 	PORT: "Web server port",
 	AUTH_ALLOW_SIGNUP:
 		'Set to "false" to disable public self-service signup routes and UI',
+	REQUIRE_EMAIL_VERIFICATION:
+		'Set to "true" (default) to require verified email for sign-in; set to "false" to allow unverified emails',
 
 	// Worker
 	WORKER_CONCURRENCY: "Number of concurrent jobs per queue (default: 5)",
@@ -259,6 +261,9 @@ function createEnvSchema(service) {
 			AUTH_ALLOW_SIGNUP: booleanLike(
 				"AUTH_ALLOW_SIGNUP must be a boolean-like value (true/false/1/0/yes/no/on/off)",
 			),
+			REQUIRE_EMAIL_VERIFICATION: booleanLike(
+				"REQUIRE_EMAIL_VERIFICATION must be a boolean-like value (true/false/1/0/yes/no/on/off)",
+			),
 
 			// Worker
 			WORKER_CONCURRENCY: optionalString,

package/templates/worker/package.json

@@ -15,6 +15,7 @@
 		"dev": "tsx watch src/index.js",
 		"start:deploy": "node src/index.js",
 		"preflight": "node src/index.js --preflight",
+		"sync-readme": "node scripts/sync-readme.js",
 		"lint": "biome format --write && biome check --write"
 	},
 	"keywords": [],

package/templates/worker/scripts/sync-readme.js

@@ -0,0 +1,41 @@
+/**
+ * Regenerate the handler-table block in README.md from JOB_NAMES.
+ *
+ * Usage (from apps/worker): pnpm sync-readme
+ *
+ * `src/readme-consistency.test.js` fails on drift between the job definitions,
+ * the registry, and the table; this command writes the fix instead of leaving
+ * the maintainer to retype it by hand.
+ */
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { jobHandlers } from "../src/handlers/index.js";
+import {
+	replaceHandlerTable,
+	TABLE_END,
+	TABLE_START,
+} from "../src/readme-table.js";
+
+const readmePath = join(
+	dirname(fileURLToPath(import.meta.url)),
+	"..",
+	"README.md",
+);
+const current = readFileSync(readmePath, "utf-8");
+
+// The scaffolded worker README is a hand-authored quickstart with no table.
+if (!current.includes(TABLE_START) || !current.includes(TABLE_END)) {
+	console.log("README has no handler-table markers; nothing to regenerate.");
+	process.exit(0);
+}
+
+const next = replaceHandlerTable(current, jobHandlers);
+
+if (next === current) {
+	console.log("README handler table is already up to date.");
+} else {
+	writeFileSync(readmePath, next);
+	console.log("Regenerated the README handler table.");
+}

package/templates/worker/src/readme-table.js

@@ -0,0 +1,68 @@
+/**
+ * Generates the README job-handler table.
+ *
+ * The row set is driven by JOB_NAMES (the jobs package is the source of truth
+ * for which jobs exist), never by the registry alone: generating from
+ * `jobHandlers` would produce a table that always matches what is registered
+ * and so could never expose a job name with no handler.
+ */
+
+import { AppError } from "@usequark/quark-core/errors";
+import { JOB_NAMES } from "@usequark/quark-jobs";
+
+/** Module under `src/handlers/` that defines each job's handler. */
+const HANDLER_MODULES = {
+	[JOB_NAMES.SEND_WELCOME_EMAIL]: "email.js",
+	[JOB_NAMES.SEND_VERIFY_EMAIL]: "email.js",
+	[JOB_NAMES.SEND_RESET_PASSWORD_EMAIL]: "email.js",
+	[JOB_NAMES.CLEANUP_ORPHANED_FILES]: "files.js",
+};
+
+export const TABLE_START = "<!-- handler-table:start -->";
+export const TABLE_END = "<!-- handler-table:end -->";
+
+/**
+ * Render the handler table for JOB_NAMES, one row per job name.
+ * @param {Record<string, Function>} jobHandlers
+ * @returns {string} markdown table (marker lines excluded)
+ */
+export function renderHandlerTable(jobHandlers) {
+	const rows = Object.values(JOB_NAMES).map((jobName) => {
+		const handler = jobHandlers[jobName];
+		const module = HANDLER_MODULES[jobName];
+		if (typeof handler !== "function" || !module) {
+			throw new AppError(
+				`No handler registration or README metadata for job: ${jobName}`,
+				500,
+				"JOB_README_ROW_MISSING",
+			);
+		}
+		return `| \`${jobName}\` | \`${handler.name}\` (\`handlers/${module}\`) |`;
+	});
+	return ["| Job name | Handler |", "|---|---|", ...rows].join("\n");
+}
+
+/**
+ * Replace the marked table block in a README with the generated one.
+ * @param {string} markdown
+ * @param {Record<string, Function>} jobHandlers
+ * @returns {string} updated markdown
+ */
+export function replaceHandlerTable(markdown, jobHandlers) {
+	const start = markdown.indexOf(TABLE_START);
+	const end = markdown.indexOf(TABLE_END);
+	if (start === -1 || end === -1 || end < start) {
+		throw new AppError(
+			"README is missing handler-table markers",
+			500,
+			"JOB_README_MARKERS_MISSING",
+		);
+	}
+	return (
+		markdown.slice(0, start + TABLE_START.length) +
+		"\n" +
+		renderHandlerTable(jobHandlers) +
+		"\n" +
+		markdown.slice(end)
+	);
+}