@usequark/quark-create-app 1.25.16 → 1.27.0

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

@@ -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/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/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/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/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(