@usequark/quark-create-app 1.23.11

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

@@ -0,0 +1,59 @@
+import { validateBody } from "@techstream/quark-core";
+import { user } from "@techstream/quark-db";
+import { NextResponse } from "next/server";
+import { z } from "zod";
+import { issueTokenPair } from "../../../../lib/jwt";
+import { handleError } from "../../error-handler";
+
+const googleAuthSchema = z.object({
+	idToken: z.string().min(1),
+});
+
+const GOOGLE_TOKENINFO_URL = "https://oauth2.googleapis.com/tokeninfo";
+
+/**
+ * POST /api/auth/google
+ * Verify Google ID token and issue a custom JWT.
+ */
+export async function POST(request) {
+	try {
+		const { idToken } = await validateBody(request, googleAuthSchema);
+
+		// Verify the token with Google's tokeninfo endpoint
+		const tokenInfoResponse = await fetch(
+			`${GOOGLE_TOKENINFO_URL}?id_token=${idToken}`,
+		);
+
+		if (!tokenInfoResponse.ok) {
+			return NextResponse.json(
+				{ message: "Invalid Google token" },
+				{ status: 401 },
+			);
+		}
+
+		const tokenInfo = await tokenInfoResponse.json();
+
+		const googleEmail = tokenInfo.email;
+		if (!googleEmail) {
+			return NextResponse.json(
+				{ message: "Google token does not contain an email" },
+				{ status: 400 },
+			);
+		}
+
+		// Find or create user
+		let existingUser = await user.findByEmail(googleEmail);
+		if (!existingUser) {
+			existingUser = await user.create({
+				email: googleEmail,
+				name: tokenInfo.name || null,
+			});
+		}
+
+		const { token, refreshToken, expiresAt } =
+			await issueTokenPair(existingUser);
+		return NextResponse.json({ token, refreshToken, expiresAt });
+	} catch (error) {
+		return handleError(error);
+	}
+}

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

@@ -0,0 +1,48 @@
+import { createLogger, validateBody } from "@techstream/quark-core";
+import { NextResponse } from "next/server";
+import { z } from "zod";
+import { issueTokenPair, verifyMobileToken } from "../../../../lib/jwt";
+import { handleError } from "../../error-handler";
+
+const logger = createLogger("auth-refresh");
+
+const refreshRequestSchema = z.object({
+	refreshToken: z.string().min(1),
+});
+
+/**
+ * POST /api/auth/refresh
+ * Exchange a refresh token for a new access token.
+ */
+export async function POST(request) {
+	try {
+		const { refreshToken } = await validateBody(request, refreshRequestSchema);
+
+		const payload = await verifyMobileToken(refreshToken);
+		if (!payload) {
+			logger.warn("Invalid refresh token");
+			return NextResponse.json(
+				{ message: "Invalid or expired refresh token" },
+				{ status: 401 },
+			);
+		}
+
+		if (payload.type !== "refresh") {
+			return NextResponse.json(
+				{ message: "Invalid token type" },
+				{ status: 401 },
+			);
+		}
+
+		const { token } = await issueTokenPair({
+			id: payload.sub,
+			email: payload.email,
+			name: payload.name,
+			role: payload.role,
+		});
+
+		return NextResponse.json({ token });
+	} catch (error) {
+		return handleError(error);
+	}
+}

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

@@ -0,0 +1,63 @@
+import {
+	createQueue,
+	hashPassword,
+	validateBody,
+	withCsrfProtection,
+} from "@techstream/quark-core";
+import { user, userRegisterSchema } from "@techstream/quark-db";
+import { JOB_NAMES, JOB_QUEUES } from "@techstream/quark-jobs";
+import { NextResponse } from "next/server";
+import { isSignupEnabled } from "@/lib/auth-signup";
+import { handleError } from "../../error-handler";
+
+export const POST = withCsrfProtection(async (request) => {
+	if (!isSignupEnabled()) {
+		return NextResponse.json(
+			{ message: "Registration is disabled." },
+			{ status: 403 },
+		);
+	}
+
+	try {
+		const data = await validateBody(request, userRegisterSchema);
+
+		// Check if user exists
+		const existing = await user.findByEmail(data.email);
+		if (existing) {
+			return NextResponse.json(
+				{ message: "User with this email already exists" },
+				{ status: 409 },
+			);
+		}
+
+		const hashedPassword = await hashPassword(data.password);
+
+		// Remove password from data before passing to create (create expects plain data object, but we need to inject hashed password)
+		// We need to update the user.create method or pass it manually.
+		// The current user.create just takes 'data'.
+
+		// Prisma create data:
+		const newUser = await user.create({
+			email: data.email,
+			name: data.name,
+			password: hashedPassword,
+		});
+
+		// Don't return the password
+		const { password: _, ...safeUser } = newUser;
+
+		// Enqueue welcome email (fire-and-forget - don't block the response)
+		try {
+			const emailQueue = createQueue(JOB_QUEUES.EMAIL);
+			await emailQueue.add(JOB_NAMES.SEND_WELCOME_EMAIL, {
+				userId: newUser.id,
+			});
+		} catch {
+			// Non-critical - user is created even if email fails to enqueue
+		}
+
+		return NextResponse.json(safeUser, { status: 201 });
+	} catch (error) {
+		return handleError(error);
+	}
+});

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

@@ -0,0 +1,44 @@
+import { validateBody, verifyPassword } from "@techstream/quark-core";
+import { user } from "@techstream/quark-db";
+import { NextResponse } from "next/server";
+import { z } from "zod";
+import { issueTokenPair } from "../../../../lib/jwt";
+import { handleError } from "../../error-handler";
+
+const tokenRequestSchema = z.object({
+	email: z.string().email(),
+	password: z.string().min(1),
+});
+
+/**
+ * POST /api/auth/token
+ * Exchange email + password for JWT tokens.
+ * Used by the mobile app for Bearer-token auth.
+ */
+export async function POST(request) {
+	try {
+		const { email, password } = await validateBody(request, tokenRequestSchema);
+
+		const existingUser = await user.findByEmail(email);
+		if (!existingUser?.password) {
+			return NextResponse.json(
+				{ message: "Invalid credentials" },
+				{ status: 401 },
+			);
+		}
+
+		const isValid = await verifyPassword(password, existingUser.password);
+		if (!isValid) {
+			return NextResponse.json(
+				{ message: "Invalid credentials" },
+				{ status: 401 },
+			);
+		}
+
+		const { token, refreshToken, expiresAt } =
+			await issueTokenPair(existingUser);
+		return NextResponse.json({ token, refreshToken, expiresAt });
+	} catch (error) {
+		return handleError(error);
+	}
+}

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

@@ -0,0 +1,40 @@
+/**
+ * CSRF Token API Endpoint
+ * Generates a CSRF token, stores it in a secure HTTP-only cookie,
+ * and returns it to the client for inclusion in request headers.
+ */
+
+import { generateCsrfToken } from "@techstream/quark-core";
+import { NextResponse } from "next/server";
+import { auth } from "@/lib/auth";
+import { getCsrfCookieOptions } from "@/lib/csrf-cookie";
+
+export async function GET(request) {
+	try {
+		const session = await auth();
+
+		if (!session) {
+			return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+		}
+
+		// Generate CSRF token
+		const csrfToken = generateCsrfToken();
+
+		const response = NextResponse.json({ csrfToken });
+
+		// Store the token in a secure HTTP-only cookie so the server can
+		// validate it on subsequent state-changing requests.
+		response.cookies.set(
+			"csrf_token",
+			csrfToken,
+			getCsrfCookieOptions(request),
+		);
+
+		return response;
+	} catch (_error) {
+		return NextResponse.json(
+			{ error: "Failed to generate CSRF token" },
+			{ status: 500 },
+		);
+	}
+}

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

@@ -0,0 +1,57 @@
+import { validateBody } from "@techstream/quark-core";
+import { prisma } from "@techstream/quark-db";
+import { NextResponse } from "next/server";
+import { z } from "zod";
+import { extractBearerPayload } from "../../../../lib/jwt";
+import { handleError } from "../../error-handler";
+
+const deviceRegisterSchema = z.object({
+	platform: z.enum(["ios", "android"]),
+	pushToken: z.string().min(1),
+	deviceId: z.string().min(1),
+});
+
+/**
+ * POST /api/device/register
+ * Register a mobile device for push notifications.
+ * Requires authentication via Bearer token.
+ */
+export async function POST(request) {
+	try {
+		const payload = await extractBearerPayload(request);
+		if (!payload?.sub) {
+			return NextResponse.json(
+				{ message: "Authentication required" },
+				{ status: 401 },
+			);
+		}
+
+		const userId = payload.sub;
+
+		const { platform, pushToken, deviceId } = await validateBody(
+			request,
+			deviceRegisterSchema,
+		);
+
+		// Upsert device record
+		await prisma.device.upsert({
+			where: {
+				userId_deviceId: { userId, deviceId },
+			},
+			update: {
+				pushToken,
+				platform,
+			},
+			create: {
+				userId,
+				platform,
+				pushToken,
+				deviceId,
+			},
+		});
+
+		return NextResponse.json({ success: true });
+	} catch (error) {
+		return handleError(error);
+	}
+}

package/templates/base-project/apps/web/src/app/api/error-handler.js

@@ -0,0 +1,23 @@
+import { AppError, createLogger } from "@techstream/quark-core";
+import { NextResponse } from "next/server";
+
+const logger = createLogger("api");
+
+export function handleError(error) {
+	logger.error("API Error", { error: error.message, stack: error.stack });
+
+	if (error instanceof AppError) {
+		return NextResponse.json(error.toJSON(), { status: error.statusCode });
+	}
+
+	// Fallback for unhandled errors
+	return NextResponse.json(
+		{
+			name: "InternalServerError",
+			message: "An unexpected error occurred",
+			statusCode: 500,
+			code: "INTERNAL_ERROR",
+		},
+		{ status: 500 },
+	);
+}

package/templates/base-project/apps/web/src/app/api/files/[id]/route.js

@@ -0,0 +1,89 @@
+/**
+ * Single File API
+ * GET    /api/files/[id] - Download / serve a file
+ * DELETE /api/files/[id] - Delete a file (owner or admin only)
+ */
+
+import {
+	createStorage,
+	ForbiddenError,
+	NotFoundError,
+	withCsrfProtection,
+} from "@techstream/quark-core";
+import { file } from "@techstream/quark-db";
+import { NextResponse } from "next/server";
+import { requireAuth } from "@/lib/auth-middleware";
+import { handleError } from "../../error-handler";
+
+/**
+ * GET /api/files/[id]
+ * Serve / download a file by its database ID.
+ * Public endpoint (no auth required) - access control is by knowledge of ID.
+ */
+export async function GET(_request, { params }) {
+	try {
+		const { id } = await params;
+
+		const record = await file.findById(id);
+		if (!record) {
+			throw new NotFoundError("File not found");
+		}
+
+		const storage = createStorage();
+		const { body, contentType } = await storage.get(record.storageKey);
+
+		const headers = new Headers();
+		headers.set("Content-Type", contentType || record.mimeType);
+		headers.set("Content-Length", String(body.length));
+		headers.set("Cache-Control", "public, max-age=31536000, immutable");
+
+		// Inline display for images; attachment download for everything else
+		const isImage = record.mimeType.startsWith("image/");
+		const safeName = record.originalName.replace(/[\\"\r\n]/g, "_");
+		const encodedName = encodeURIComponent(record.originalName);
+		headers.set(
+			"Content-Disposition",
+			isImage
+				? `inline; filename="${safeName}"; filename*=UTF-8''${encodedName}`
+				: `attachment; filename="${safeName}"; filename*=UTF-8''${encodedName}`,
+		);
+
+		return new Response(body, { status: 200, headers });
+	} catch (error) {
+		return handleError(error);
+	}
+}
+
+/**
+ * DELETE /api/files/[id]
+ * Delete a file. Only the uploader or an admin can delete.
+ */
+export const DELETE = withCsrfProtection(async (_request, { params }) => {
+	try {
+		const session = await requireAuth();
+		const { id } = await params;
+
+		const record = await file.findById(id);
+		if (!record) {
+			throw new NotFoundError("File not found");
+		}
+
+		// Authorization: uploader or admin
+		const isOwner = record.uploadedById === session.user.id;
+		const isAdmin = session.user.role === "admin";
+		if (!isOwner && !isAdmin) {
+			throw new ForbiddenError("You can only delete your own files");
+		}
+
+		// Remove from storage
+		const storage = createStorage();
+		await storage.delete(record.storageKey);
+
+		// Remove database record
+		await file.delete(record.id);
+
+		return NextResponse.json({ message: "File deleted" });
+	} catch (error) {
+		return handleError(error);
+	}
+});

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

@@ -0,0 +1,120 @@
+/**
+ * File Upload API
+ * POST /api/files - Upload a file (multipart/form-data)
+ * GET  /api/files - List current user's files
+ */
+
+import {
+	createStorage,
+	generateStorageKey,
+	parseMultipart,
+	parsePaginationQuery,
+	validateFile,
+	withCsrfProtection,
+} from "@techstream/quark-core";
+import { file } from "@techstream/quark-db";
+import { NextResponse } from "next/server";
+import { requireAuth } from "@/lib/auth-middleware";
+import { handleError } from "../error-handler";
+
+/**
+ * POST /api/files
+ * Upload one or more files via multipart/form-data.
+ * Requires authentication.
+ */
+export const POST = withCsrfProtection(async (request) => {
+	try {
+		const session = await requireAuth();
+
+		// Parse multipart body
+		const { files: parsedFiles } = await parseMultipart(request);
+
+		if (parsedFiles.length === 0) {
+			return NextResponse.json(
+				{ message: "No files provided" },
+				{ status: 400 },
+			);
+		}
+
+		const storage = createStorage();
+		const results = [];
+
+		for (const parsed of parsedFiles) {
+			// Validate each file
+			const validation = validateFile({
+				filename: parsed.filename,
+				mimeType: parsed.mimeType,
+				size: parsed.size,
+				buffer: parsed.buffer,
+			});
+
+			if (!validation.valid) {
+				return NextResponse.json(
+					{ message: validation.error, filename: parsed.filename },
+					{ status: 422 },
+				);
+			}
+
+			// Generate storage key and upload
+			const storageKey = generateStorageKey(parsed.filename);
+
+			await storage.put(storageKey, parsed.buffer, {
+				contentType: parsed.mimeType,
+			});
+
+			// Save metadata to database
+			const record = await file.create({
+				filename: storageKey.split("/").pop(),
+				originalName: parsed.filename,
+				mimeType: parsed.mimeType,
+				size: parsed.size,
+				storageKey,
+				storageProvider: storage.provider,
+				uploadedById: session.user.id,
+			});
+
+			results.push({
+				id: record.id,
+				originalName: record.originalName,
+				mimeType: record.mimeType,
+				size: record.size,
+				url: `/api/files/${record.id}`,
+				createdAt: record.createdAt,
+			});
+		}
+
+		const status = results.length === 1 ? 201 : 200;
+		const body = results.length === 1 ? results[0] : { files: results };
+
+		return NextResponse.json(body, { status });
+	} catch (error) {
+		return handleError(error);
+	}
+});
+
+/**
+ * GET /api/files
+ * List files uploaded by the current user.
+ */
+export async function GET(request) {
+	try {
+		const session = await requireAuth();
+
+		const { searchParams } = new URL(request.url);
+		const { skip, take } = parsePaginationQuery(searchParams);
+		const files = await file.findByUploader(session.user.id, { skip, take });
+
+		const mapped = files.map((f) => ({
+			id: f.id,
+			originalName: f.originalName,
+			mimeType: f.mimeType,
+			size: f.size,
+			url: `/api/files/${f.id}`,
+			createdAt: f.createdAt,
+		}));
+
+		return NextResponse.json(mapped);
+	} catch (error) {
+		return handleError(error);
+	}
+}

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

@@ -0,0 +1,160 @@
+/**
+ * Health Check Endpoint
+ * Verifies the application and its dependencies are functioning correctly.
+ * Times out after 5 seconds to prevent hanging.
+ */
+
+import {
+	createLogger,
+	createStorage,
+	getRegisteredQueues,
+	pingRedis,
+} from "@techstream/quark-core";
+import { pingDatabase } from "@techstream/quark-db";
+import { NextResponse } from "next/server";
+
+const logger = createLogger("health");
+
+/** Overall timeout for the health check (ms). */
+const HEALTH_CHECK_TIMEOUT = 5000;
+
+export async function GET() {
+	try {
+		const result = await new Promise((resolve, reject) => {
+			const timer = setTimeout(
+				() => reject(new Error("Health check timed out")),
+				HEALTH_CHECK_TIMEOUT,
+			);
+			runHealthChecks().then(
+				(val) => {
+					clearTimeout(timer);
+					resolve(val);
+				},
+				(err) => {
+					clearTimeout(timer);
+					reject(err);
+				},
+			);
+		});
+
+		return NextResponse.json(result, {
+			status: result.status === "error" ? 503 : 200,
+		});
+	} catch (error) {
+		logger.error("Health check failed", {
+			error: error.message,
+			stack: error.stack,
+		});
+		return NextResponse.json(
+			{
+				status: "error",
+				timestamp: new Date().toISOString(),
+				message: "Service health check failed",
+			},
+			{ status: 500 },
+		);
+	}
+}
+
+/**
+ * Runs all individual health checks and aggregates the results.
+ * @returns {Promise<{ status: string, timestamp: string, checks: Record<string, object> }>}
+ */
+async function runHealthChecks() {
+	const health = {
+		status: "ok",
+		timestamp: new Date().toISOString(),
+		checks: {},
+	};
+
+	// Check database connectivity
+	const dbResult = await pingDatabase();
+	if (dbResult.status === "ok") {
+		health.checks.database = { status: "ok", latencyMs: dbResult.latencyMs };
+	} else {
+		health.checks.database = {
+			status: "error",
+			message: dbResult.message,
+		};
+		health.status = "degraded";
+	}
+
+	// Check Redis connectivity (actual PING)
+	const redisResult = await pingRedis();
+	if (redisResult.status === "ok") {
+		health.checks.redis = { status: "ok", latencyMs: redisResult.latencyMs };
+	} else {
+		health.checks.redis = {
+			status: "error",
+			message: redisResult.message,
+		};
+		health.status = "degraded";
+	}
+
+	// Check storage connectivity
+	const storageResult = await checkStorage();
+	health.checks.storage = storageResult;
+	if (storageResult.status === "error") {
+		health.status = "degraded";
+	}
+
+	// Check queue depths (only when queues are registered in this process)
+	const registeredQueues = getRegisteredQueues();
+	if (registeredQueues.size > 0) {
+		const entries = [...registeredQueues.entries()];
+		const results = await Promise.allSettled(
+			entries.map(([, queue]) =>
+				Promise.all([
+					queue.getWaitingCount(),
+					queue.getActiveCount(),
+					queue.getFailedCount(),
+				]),
+			),
+		);
+
+		const queueChecks = {};
+		for (let i = 0; i < entries.length; i++) {
+			const [name] = entries[i];
+			const result = results[i];
+			if (result.status === "fulfilled") {
+				const [waiting, active, failed] = result.value;
+				queueChecks[name] = { status: "ok", waiting, active, failed };
+			} else {
+				const message =
+					process.env.NODE_ENV === "production"
+						? "Queue unavailable"
+						: result.reason?.message;
+				queueChecks[name] = { status: "error", message };
+				health.status = "degraded";
+			}
+		}
+		health.checks.queues = queueChecks;
+	}
+
+	return health;
+}
+
+/**
+ * Verifies storage is reachable and writable by writing then deleting a
+ * small sentinel object. Uses whichever provider is configured via
+ * STORAGE_PROVIDER (defaults to "local" when unset).
+ * @returns {Promise<{ status: string, provider: string, message?: string }>}
+ */
+async function checkStorage() {
+	const provider = process.env.STORAGE_PROVIDER || "local";
+	try {
+		const storage = createStorage();
+		const sentinelKey = ".health-check-sentinel";
+		await storage.put(sentinelKey, Buffer.from("ok"), {
+			contentType: "text/plain",
+		});
+		await storage.delete(sentinelKey);
+		return { status: "ok", provider };
+	} catch (error) {
+		const message =
+			process.env.NODE_ENV === "production"
+				? "Storage unavailable"
+				: error.message;
+		return { status: "error", provider, message };
+	}
+}