@usequark/quark-create-app 1.23.11

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

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

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

@@ -0,0 +1,191 @@
+import { PrismaAdapter } from "@auth/prisma-adapter";
+import {
+	createAuthConfig,
+	createLogger,
+	verifyPassword,
+} from "@techstream/quark-core";
+import { Prisma, prisma, user } from "@techstream/quark-db";
+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";
+
+const logger = createLogger({ name: "auth" });
+const STALE_SESSION_PATTERN = /jwtsessionerror|no matching decryption secret/i;
+
+function describeAuthIssue(issue, seen = new Set()) {
+	if (!issue) {
+		return "";
+	}
+
+	if (typeof issue === "string") {
+		return issue;
+	}
+
+	if (typeof issue === "number" || typeof issue === "boolean") {
+		return String(issue);
+	}
+
+	if (typeof issue !== "object" || seen.has(issue)) {
+		return "";
+	}
+
+	seen.add(issue);
+
+	const parts = [];
+	for (const key of ["name", "type", "code", "message"]) {
+		const value = issue[key];
+		if (typeof value === "string" && value) {
+			parts.push(value);
+		}
+	}
+
+	for (const key of ["cause", "error", "details"]) {
+		const nested = describeAuthIssue(issue[key], seen);
+		if (nested) {
+			parts.push(nested);
+		}
+	}
+
+	return parts.join(" ");
+}
+
+function isIgnorableSessionError(issue) {
+	return STALE_SESSION_PATTERN.test(describeAuthIssue(issue));
+}
+
+const providers = [
+	CredentialsProvider({
+		name: "Credentials",
+		credentials: {
+			email: { label: "Email", type: "email" },
+			password: { label: "Password", type: "password" },
+		},
+		async authorize(credentials) {
+			if (!credentials?.email || !credentials?.password) {
+				return null;
+			}
+
+			try {
+				const existingUser = await user.findByEmail(credentials.email);
+
+				if (!existingUser?.password) {
+					return null;
+				}
+
+				const isValid = await verifyPassword(
+					credentials.password,
+					existingUser.password,
+				);
+
+				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.
+				// PrismaClientInitializationError: client could not connect on startup.
+				// PrismaClientKnownRequestError P1xxx: connection lost / timeout mid-request.
+				const isDbDown =
+					err instanceof Prisma.PrismaClientInitializationError ||
+					(err instanceof Prisma.PrismaClientKnownRequestError &&
+						err.errorCode?.startsWith("P1"));
+				if (isDbDown) {
+					logger.error("Database unavailable during authentication", {
+						errorCode: err.errorCode,
+					});
+					throw err;
+				}
+				// For all other unexpected errors, log and fail closed.
+				logger.error("Auth authorize error", {
+					message: err?.message ?? String(err),
+				});
+				return null;
+			}
+		},
+	}),
+];
+
+if (process.env.GITHUB_ID && process.env.GITHUB_SECRET) {
+	providers.push(
+		GithubProvider({
+			clientId: process.env.GITHUB_ID,
+			clientSecret: process.env.GITHUB_SECRET,
+		}),
+	);
+}
+
+if (process.env.GOOGLE_CLIENT_ID && process.env.GOOGLE_CLIENT_SECRET) {
+	providers.push(
+		GoogleProvider({
+			clientId: process.env.GOOGLE_CLIENT_ID,
+			clientSecret: process.env.GOOGLE_CLIENT_SECRET,
+		}),
+	);
+}
+
+export function getAuthOptions() {
+	return createAuthConfig({
+		adapter: PrismaAdapter(prisma),
+		providers: providers,
+		logger: {
+			error(...issues) {
+				if (issues.some(isIgnorableSessionError)) {
+					return;
+				}
+
+				logger.error("Auth.js error", {
+					details: issues.map((issue) => describeAuthIssue(issue)).join(" | "),
+				});
+			},
+		},
+		session: {
+			strategy: "jwt",
+		},
+	});
+}
+
+let authInstance = null;
+
+function getAuthInstance() {
+	if (!authInstance) {
+		authInstance = NextAuth(getAuthOptions());
+	}
+	return authInstance;
+}
+
+export function getAuth() {
+	return getAuthInstance();
+}
+
+export async function auth() {
+	try {
+		return await getAuthInstance().auth();
+	} catch (error) {
+		if (isIgnorableSessionError(error)) {
+			return null;
+		}
+
+		throw error;
+	}
+}
+
+export const handlers = new Proxy(
+	{},
+	{
+		get(_target, prop) {
+			return getAuthInstance().handlers[prop];
+		},
+	},
+);
+
+export const signIn = (...args) => getAuthInstance().signIn(...args);
+export const signOut = (...args) => getAuthInstance().signOut(...args);

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

@@ -0,0 +1,11 @@
+import { shouldUseSecureAuthCookie } from "./proxy-auth.js";
+
+export function getCsrfCookieOptions(request) {
+	return {
+		httpOnly: true,
+		secure: shouldUseSecureAuthCookie(request),
+		sameSite: "strict",
+		path: "/",
+		maxAge: 60 * 60,
+	};
+}

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

@@ -0,0 +1,84 @@
+import { AppError, getAuthSecret } from "@techstream/quark-core";
+import { jwtVerify, SignJWT } from "jose";
+
+const ISSUER = "quark-mobile";
+const ACCESS_TOKEN_EXPIRY = "1h";
+const REFRESH_TOKEN_EXPIRY = "30d";
+
+/**
+ * Get the shared secret key for signing/verifying mobile JWTs.
+ * Returns null if NEXTAUTH_SECRET is not configured.
+ */
+function getSecretKey() {
+	const secret = getAuthSecret();
+	if (!secret) return null;
+	return new TextEncoder().encode(secret);
+}
+
+/**
+ * Issue an access + refresh token pair for a user.
+ * @param {{ id: string, email: string, name: string | null, role: string }} user
+ * @returns {{ token: string, refreshToken: string, expiresAt: string }}
+ */
+export async function issueTokenPair(user) {
+	const secretKey = getSecretKey();
+	if (!secretKey) throw new AppError("NEXTAUTH_SECRET not configured", 500);
+
+	const now = Math.floor(Date.now() / 1000);
+
+	const [token, refreshToken] = await Promise.all([
+		new SignJWT({
+			sub: user.id,
+			email: user.email,
+			name: user.name,
+			role: user.role,
+		})
+			.setProtectedHeader({ alg: "HS256" })
+			.setIssuedAt(now)
+			.setExpirationTime(ACCESS_TOKEN_EXPIRY)
+			.setIssuer(ISSUER)
+			.sign(secretKey),
+		new SignJWT({
+			sub: user.id,
+			type: "refresh",
+		})
+			.setProtectedHeader({ alg: "HS256" })
+			.setIssuedAt(now)
+			.setExpirationTime(REFRESH_TOKEN_EXPIRY)
+			.setIssuer(ISSUER)
+			.sign(secretKey),
+	]);
+
+	const expiresAt = new Date(now * 1000 + 60 * 60 * 1000).toISOString();
+	return { token, refreshToken, expiresAt };
+}
+
+/**
+ * Verify a mobile JWT and return its payload.
+ * @param {string} token
+ * @returns {Promise<import("jose").JWTPayload | null>} payload or null if invalid
+ */
+export async function verifyMobileToken(token) {
+	const secretKey = getSecretKey();
+	if (!secretKey) return null;
+
+	try {
+		const result = await jwtVerify(token, secretKey, { issuer: ISSUER });
+		return result.payload;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Extract and verify a Bearer token from a Request's Authorization header.
+ * @param {Request} request
+ * @returns {Promise<import("jose").JWTPayload | null>} payload or null if missing/invalid
+ */
+export async function extractBearerPayload(request) {
+	const authHeader = request.headers.get("authorization");
+	if (!authHeader?.startsWith("Bearer ")) return null;
+
+	const token = authHeader.slice(7);
+	return verifyMobileToken(token);
+}

package/templates/base-project/apps/web/src/lib/load-crm-config.js

@@ -0,0 +1,35 @@
+import { access } from "node:fs/promises";
+import path from "node:path";
+
+const CRM_PATHS = [
+	"packages/crm/src/config.js",
+	"../../packages/crm/src/config.js",
+	"../../../../../../packages/crm/src/config.js",
+];
+
+let crmAvailable;
+
+async function checkCrmExists() {
+	for (const relativePath of CRM_PATHS) {
+		try {
+			await access(path.resolve(process.cwd(), relativePath));
+			return true;
+		} catch {}
+	}
+	return false;
+}
+
+export async function loadCrmConfig() {
+	if (crmAvailable === undefined) {
+		crmAvailable = await checkCrmExists();
+	}
+	return crmAvailable ? { present: true } : null;
+}
+
+export async function hasCrmFeature() {
+	return Boolean(await loadCrmConfig());
+}
+
+export function resetCrmConfigCache() {
+	crmAvailable = undefined;
+}

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

@@ -0,0 +1,33 @@
+import { NextRequest } from "next/server.js";
+
+export function normalizeAuthRequest(request) {
+	if (process.env.NODE_ENV !== "development") {
+		return request;
+	}
+
+	const forwardedHost = request.headers.get("x-forwarded-host");
+	const host = request.headers.get("host");
+	const incomingHost = forwardedHost || host;
+
+	if (!incomingHost) {
+		return request;
+	}
+
+	const forwardedProto = request.headers.get("x-forwarded-proto");
+	const incomingProtocol = forwardedProto
+		? forwardedProto.split(",")[0].trim()
+		: "http";
+	const currentUrl = new URL(request.url);
+	const currentOrigin = `${currentUrl.protocol}//${currentUrl.host}`;
+	const incomingOrigin = `${incomingProtocol}://${incomingHost}`;
+
+	if (currentOrigin === incomingOrigin) {
+		return request;
+	}
+
+	const normalizedUrl = new URL(request.url);
+	normalizedUrl.protocol = `${incomingProtocol}:`;
+	normalizedUrl.host = incomingHost;
+
+	return new NextRequest(normalizedUrl, request);
+}

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

@@ -0,0 +1,80 @@
+import { getAuthSecret } from "@techstream/quark-core/auth";
+import { getToken } from "next-auth/jwt";
+
+const STRICT_AUTH_RATE_LIMIT_ROUTES = new Set([
+	"/api/auth/callback/credentials",
+	"/api/auth/register",
+	"/api/auth/signin/credentials",
+]);
+
+function getForwardedProtocol(request) {
+	const forwardedProto = request.headers.get("x-forwarded-proto");
+	if (!forwardedProto) return null;
+
+	const [protocol] = forwardedProto
+		.split(",")
+		.map((value) => value.trim())
+		.filter(Boolean);
+
+	if (!protocol) return null;
+	return protocol.endsWith(":") ? protocol : `${protocol}:`;
+}
+
+function getFallbackProtocol() {
+	const rawUrl =
+		process.env.AUTH_URL || process.env.NEXTAUTH_URL || process.env.APP_URL;
+
+	if (!rawUrl) return "http:";
+
+	try {
+		return new URL(rawUrl).protocol;
+	} catch {
+		return "http:";
+	}
+}
+
+export function getRequestProtocol(request) {
+	return (
+		getForwardedProtocol(request) ||
+		request.nextUrl?.protocol ||
+		getFallbackProtocol()
+	);
+}
+
+export function shouldUseSecureAuthCookie(request) {
+	const forwardedProtocol = getForwardedProtocol(request);
+	if (forwardedProtocol) {
+		return forwardedProtocol === "https:";
+	}
+
+	return getRequestProtocol(request) === "https:";
+}
+
+export async function getProxyToken(request) {
+	const secret = getAuthSecret();
+	if (!secret) return null;
+
+	const secureCookiePreferences = shouldUseSecureAuthCookie(request)
+		? [true, false]
+		: [false, true];
+
+	for (const secureCookie of secureCookiePreferences) {
+		const token = await getToken({
+			req: request,
+			secret,
+			secureCookie,
+		});
+
+		if (token) {
+			return token;
+		}
+	}
+
+	return null;
+}
+
+export function getRateLimitBucket(pathname, method = "GET") {
+	return method === "POST" && STRICT_AUTH_RATE_LIMIT_ROUTES.has(pathname)
+		? "auth"
+		: "api";
+}

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

@@ -0,0 +1,25 @@
+export function isWebsiteIndexable(env = process.env) {
+	const productionEnv = (env.NODE_ENV || "").toLowerCase() === "production";
+	const explicitAllow = (env.ALLOW_INDEXING || "").toLowerCase() === "true";
+	return productionEnv && explicitAllow;
+}
+
+export function getMetadataRobots(env = process.env) {
+	if (isWebsiteIndexable(env)) {
+		return {
+			index: true,
+			follow: true,
+		};
+	}
+
+	return {
+		index: false,
+		follow: false,
+		nocache: true,
+		googleBot: {
+			index: false,
+			follow: false,
+			noimageindex: true,
+		},
+	};
+}

package/templates/base-project/apps/web/src/lib/seo/site-metadata.js

@@ -0,0 +1,74 @@
+import { config, getAppUrl } from "@techstream/quark-config";
+import { getMetadataRobots } from "./indexing.js";
+
+export function getSiteMetadata() {
+	const appUrl = getAppUrl();
+	const { appName, appDescription } = config;
+
+	return {
+		metadataBase: new URL(appUrl),
+		title: {
+			default: appName,
+			template: `%s | ${appName}`,
+		},
+		description: appDescription,
+		applicationName: appName,
+		alternates: {
+			canonical: "/",
+		},
+		openGraph: {
+			type: "website",
+			url: appUrl,
+			title: appName,
+			description: appDescription,
+			siteName: appName,
+		},
+		twitter: {
+			card: "summary",
+			title: appName,
+			description: appDescription,
+		},
+		robots: getMetadataRobots(),
+	};
+}
+
+/**
+ * Build per-page metadata. Titles are rendered as `{ absolute }` so the
+ * root layout template (`%s | Brand`) is applied exactly once.
+ *
+ * Page-title conventions (see the `seo` skill): keyword-first for
+ * money/service pages, `Entity | Brand` for detail pages, 50-60 chars.
+ * The SEO title may differ from the visible H1 on CMS-driven pages.
+ *
+ * @param {object} options
+ * @param {string} options.title - SEO title (brand suffix appended).
+ * @param {string} [options.description] - Meta description (150-160 chars).
+ * @param {string} [options.path] - Route path used for the canonical URL.
+ * @param {boolean} [options.noIndex=false] - Force noindex/noindex robots.
+ */
+export function getPageMetadata({ title, description, path, noIndex = false }) {
+	const appUrl = getAppUrl();
+	const { appName, appDescription } = config;
+	const resolvedDescription = description ?? appDescription;
+
+	return {
+		title: {
+			absolute: `${title} | ${appName}`,
+		},
+		description: resolvedDescription,
+		alternates: path ? { canonical: path } : undefined,
+		openGraph: {
+			type: "website",
+			url: path ? new URL(path, appUrl).toString() : appUrl,
+			title,
+			description: resolvedDescription,
+			siteName: appName,
+		},
+		twitter: {
+			card: "summary",
+			title,
+			description: resolvedDescription,
+		},
+		robots: noIndex ? { index: false, follow: false } : getMetadataRobots(),
+	};
+}

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

@@ -0,0 +1,22 @@
+export const STATIC_SITEMAP_ROUTES = [
+	{ path: "/", changeFrequency: "daily", priority: 1 },
+];
+
+export function buildSitemapEntries({
+	appUrl,
+	staticRoutes = STATIC_SITEMAP_ROUTES,
+	publicContentEntries = [],
+}) {
+	return [
+		...staticRoutes.map((route) => ({
+			url: `${appUrl}${route.path}`,
+			changeFrequency: route.changeFrequency,
+			priority: route.priority,
+		})),
+		...publicContentEntries.map((entry) => ({
+			url: `${appUrl}${entry.path}`,
+			changeFrequency: entry.changeFrequency,
+			priority: entry.priority,
+		})),
+	];
+}

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

@@ -0,0 +1,55 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadConfig } from "@techstream/quark-config";
+import { createLogger } from "@techstream/quark-core";
+import { pingDatabase } from "@techstream/quark-db";
+
+const logger = createLogger("web-preflight");
+
+export const DEFAULT_DEV_PREFLIGHT_TIMEOUT = 1500;
+
+export async function runWebPreflight({
+	loadAppConfig = () => loadConfig({}, { fresh: true }),
+	ping = pingDatabase,
+	timeout = DEFAULT_DEV_PREFLIGHT_TIMEOUT,
+} = {}) {
+	loadAppConfig();
+	return ping({ timeout });
+}
+
+export function formatWebPreflightFailure(result) {
+	return [
+		`Database preflight failed: ${result.message}`,
+		"Start PostgreSQL or check DATABASE_URL / POSTGRES_* before running `pnpm dev`.",
+	].join("\n");
+}
+
+async function main() {
+	if (process.env.QUARK_SKIP_DEV_PREFLIGHT === "1") {
+		logger.info("Skipping web dev preflight (QUARK_SKIP_DEV_PREFLIGHT=1)");
+		return;
+	}
+
+	logger.info("Running web dev preflight...");
+
+	try {
+		const result = await runWebPreflight();
+
+		if (result.status === "ok") {
+			logger.info(`Database ready (${result.latencyMs}ms)`);
+			return;
+		}
+
+		logger.error(formatWebPreflightFailure(result));
+		process.exit(1);
+	} catch (error) {
+		logger.error(error?.message ?? String(error));
+		process.exit(1);
+	}
+}
+
+const __filename = fileURLToPath(import.meta.url);
+
+if (process.argv[1] && path.resolve(process.argv[1]) === __filename) {
+	void main();
+}