@usequark/quark-create-app 1.25.5 → 1.25.7

package/package.json

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

package/templates/base-project/.env.railway.example

@@ -23,6 +23,16 @@ AUTH_ALLOW_SIGNUP=false
 # Must be at least 32 characters or startup validation fails.
 NEXTAUTH_SECRET=CHANGE_ME_TO_A_32_CHARACTERS_OR_LONGER_SECRET
 
+# --- Optional OAuth providers ---
+# Unset by default; social sign-in stays off. These are the credentials the
+# /api/auth/google and /api/auth/apple routes bind tokens to. Server-only -
+# do not prefix them with NEXT_PUBLIC_.
+# GOOGLE_CLIENT_ID=
+# GOOGLE_CLIENT_SECRET=
+# APPLE_CLIENT_ID=
+# GITHUB_ID=
+# GITHUB_SECRET=
+
 # APP_URL is the canonical public URL. NEXTAUTH_URL is derived automatically.
 # Uncomment only if you need to override it explicitly.
 # NEXTAUTH_URL=https://__QUARK_PROJECT_NAME__.railway.app

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

@@ -26,11 +26,28 @@ NEXTAUTH_URL=http://localhost:3005
 NEXTAUTH_SECRET=replace_with_a_long_random_secret
 
 # --- OAuth Providers (optional) ---
-# Uncomment and fill in to enable GitHub / Google sign-in
-# GITHUB_ID=your_github_oauth_app_client_id
-# GITHUB_SECRET=your_github_oauth_app_client_secret
-# GOOGLE_CLIENT_ID=your_google_oauth_client_id
-# GOOGLE_CLIENT_SECRET=your_google_oauth_client_secret
+# Leave every variable in this section unset and social sign-in is off.
+# Nothing in Quark requires these.
+#
+# Each provider is enabled by its client id alone. These are the credentials
+# the /api/auth/google and /api/auth/apple routes will bind tokens to.
+#
+# GitHub - Get credentials at: https://github.com/settings/developers
+# GITHUB_ID=your_github_client_id
+# GITHUB_SECRET=your_github_client_secret
+
+# Google - Get credentials at: https://console.cloud.google.com/apis/credentials
+# Both halves together add the Google button to the web sign-in page.
+# The client id is also the token audience the mobile app's POST /api/auth/google
+# will be checked against.
+# GOOGLE_CLIENT_ID=your_google_client_id
+# GOOGLE_CLIENT_SECRET=your_google_client_secret
+
+# Apple - Create a Services ID at: https://developer.apple.com/account/resources/identifiers/list/serviceId
+# The Services ID is the token audience the mobile app's POST /api/auth/apple
+# will be checked against. No secret is involved - that route verifies the
+# signed identity token itself.
+# APPLE_CLIENT_ID=com.example.yourapp
 
 # --- SEO / Indexing ---
 # Set to "true" ONLY in your production deployment.

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

@@ -6,21 +6,32 @@
 
 import { generateCsrfToken } from "@usequark/quark-core";
 import { NextResponse } from "next/server";
-import { auth } from "@/lib/auth";
 import { getCsrfCookieOptions } from "@/lib/csrf-cookie";
 
+/**
+ * Headers applied to every response.
+ *
+ * `no-store` is load-bearing, not hygiene. The body of this response *is* a
+ * write credential: paired with the cookie it sets, it authorises the holder's
+ * next mutating request. A shared cache that stored it could hand the token to
+ * a second caller, who would then be able to write as the first — so this
+ * response must never be cached, by the browser or anything between it and the
+ * client. `Vary: Cookie` keeps that true for a cache that keys on request
+ * headers rather than obeying `no-store` outright.
+ */
+const NO_STORE_HEADERS = {
+	"Cache-Control": "no-store, no-cache, must-revalidate",
+	Vary: "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 });
+		const response = NextResponse.json(
+			{ csrfToken },
+			{ headers: NO_STORE_HEADERS },
+		);
 
 		// Store the token in a secure HTTP-only cookie so the server can
 		// validate it on subsequent state-changing requests.
@@ -34,7 +45,7 @@ export async function GET(request) {
 	} catch (_error) {
 		return NextResponse.json(
 			{ error: "Failed to generate CSRF token" },
-			{ status: 500 },
+			{ status: 500, headers: NO_STORE_HEADERS },
 		);
 	}
 }

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

@@ -1,5 +1,6 @@
 "use client";
 
+import { clearCsrfToken, getCsrfToken } from "@usequark/quark-core/csrf-client";
 import {
 	Button,
 	ErrorBanner,
@@ -98,16 +99,55 @@ function RegisterForm() {
 		setPasswordError("");
 		setLoading(true);
 
-		const res = await fetch("/api/auth/register", {
+		// The CSRF token has to be in hand before the write. `GET /api/csrf` sets
+		// the matching httpOnly cookie and returns the same value; the server
+		// compares the two, so a request that arrives without the cookie is
+		// rejected before the handler runs. This page is pre-authentication, which
+		// is why the endpoint mints tokens for callers with no session.
+		//
+		// Both the token fetch and the write can fail on the network, and this
+		// handler has already set `loading`. Without a catch, either one would
+		// leave the button spinning forever.
+		try {
+			const res = await postRegistration(await getCsrfToken());
+
+			// The cache refetches on a timer, which covers expiry. It cannot cover
+			// the server rotating the cookie underneath us — a sign-out, or anything
+			// else that clears cookies — and that surfaces as a rejected write with
+			// nothing visibly wrong. Drop the stale token and try once more; a
+			// second failure is a real failure and falls through to the banner.
+			if (res.status === 401) {
+				clearCsrfToken();
+				return await completeRegistration(
+					await postRegistration(await getCsrfToken()),
+				);
+			}
+
+			return await completeRegistration(res);
+		} catch {
+			setError("Could not reach the server. Try again.");
+			setLoading(false);
+		}
+	}
+
+	/** POST the form to /api/auth/register with the given token. */
+	async function postRegistration(csrfToken) {
+		return await fetch("/api/auth/register", {
 			method: "POST",
-			headers: { "Content-Type": "application/json" },
+			headers: {
+				"Content-Type": "application/json",
+				"X-CSRF-Token": csrfToken,
+			},
 			body: JSON.stringify({
 				email: email.trim(),
 				password,
 				name: name.trim() || undefined,
 			}),
 		});
+	}
 
+	/** Surface a failure, or sign the new account in. */
+	async function completeRegistration(res) {
 		if (!res.ok) {
 			const body = await res.json().catch(() => ({}));
 			setError(body.message || "Registration failed. Try again.");

package/templates/config/package.json

@@ -8,6 +8,7 @@
 		"./rate-limit": "./src/rate-limit.js",
 		"./app-url": "./src/app-url.js",
 		"./environment": "./src/environment.js",
+		"./oauth": "./src/oauth.js",
 		"./load-config": "./src/load-config.js",
 		"./validate-env": "./src/validate-env.js",
 		"./redis": "./src/redis.js"

package/templates/config/src/index.js

@@ -11,6 +11,13 @@ export {
 	resolveEnvironment,
 } from "./environment.js";
 export { getConfig, loadConfig, resetConfig } from "./load-config.js";
+export {
+	getAppleClientId,
+	getGoogleClientId,
+	isAppleAuthEnabled,
+	isAudienceValid,
+	isGoogleAuthEnabled,
+} from "./oauth.js";
 export { applyRateLimit, rateLimit } from "./rate-limit.js";
 export { closeSharedRedisClient, getSharedRedisClient } from "./redis.js";
 export { loadEnv } from "./validate-env.js";

package/templates/config/src/oauth.js

@@ -0,0 +1,94 @@
+/**
+ * OAuth provider configuration.
+ *
+ * Every provider here is optional. Nothing in Quark requires an OAuth client
+ * id, so an app that never enables social sign-in reads `undefined` from these
+ * helpers and is unaffected.
+ *
+ * The contract the auth routes depend on: a provider is either fully
+ * configured or it is *off*. There is no third state in which a route serves
+ * requests with a weakened trust check. A caller that reaches
+ * `/api/auth/google` without `GOOGLE_CLIENT_ID` set gets a refusal, not an
+ * unverified login — the route is a public endpoint, so "nobody configured it"
+ * is not a reason to leave it serving.
+ *
+ * The client id is the `aud` claim on the id token the provider issues, which
+ * is what binds a token to *this* deployment. Without it, a token minted by any
+ * other app registered with the same provider verifies fine and would be
+ * accepted here.
+ */
+
+/**
+ * Reads a client id, treating a blank value as unset.
+ *
+ * A variable set to `""` or whitespace survives `process.env` but is not a
+ * usable client id. Treating it as configured would turn the audience check
+ * into a comparison against the empty string and reject every real token,
+ * which reads as "sign-in is broken" rather than "sign-in is off".
+ *
+ * @param {string | undefined} value
+ * @returns {string | undefined} The trimmed id, or undefined when blank.
+ */
+function readClientId(value) {
+	const trimmed = value?.trim();
+	return trimmed ? trimmed : undefined;
+}
+
+/**
+ * The Google OAuth client id, or undefined when Google sign-in is not configured.
+ *
+ * @returns {string | undefined}
+ */
+export function getGoogleClientId() {
+	return readClientId(process.env.GOOGLE_CLIENT_ID);
+}
+
+/**
+ * The Apple Services ID, or undefined when Apple sign-in is not configured.
+ *
+ * @returns {string | undefined}
+ */
+export function getAppleClientId() {
+	return readClientId(process.env.APPLE_CLIENT_ID);
+}
+
+/**
+ * Whether Google sign-in is enabled on this deployment.
+ *
+ * @returns {boolean}
+ */
+export function isGoogleAuthEnabled() {
+	return Boolean(getGoogleClientId());
+}
+
+/**
+ * Whether Apple sign-in is enabled on this deployment.
+ *
+ * @returns {boolean}
+ */
+export function isAppleAuthEnabled() {
+	return Boolean(getAppleClientId());
+}
+
+/**
+ * Compares a token's `aud` claim against the expected client id.
+ *
+ * Used for Google, where the token is verified out of process by the provider's
+ * own introspection endpoint and the claims arrive as parsed JSON. Apple
+ * verifies the signature locally, so its audience is passed to `jwtVerify`
+ * instead and never comes through here.
+ *
+ * @param {unknown} actual - The `aud` claim from the verified token.
+ * @param {string | undefined} expected - The configured client id.
+ * @returns {boolean} False when either side is missing, so an unconfigured
+ *   deployment cannot pass by accident.
+ */
+export function isAudienceValid(actual, expected) {
+	if (typeof actual !== "string" || actual === "") {
+		return false;
+	}
+	if (typeof expected !== "string" || expected === "") {
+		return false;
+	}
+	return actual === expected;
+}

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

@@ -85,6 +85,15 @@ const ENV_DESCRIPTIONS = {
 	NEXTAUTH_SECRET: "NextAuth secret for JWT signing",
 	NEXTAUTH_URL: "NextAuth callback URL (derived from APP_URL if not set)",
 
+	// OAuth (optional — each provider is inert unless its client id is set)
+	GITHUB_ID: "GitHub OAuth client id for NextAuth sign-in",
+	GITHUB_SECRET: "GitHub OAuth client secret for NextAuth sign-in",
+	GOOGLE_CLIENT_ID:
+		"Google OAuth client id — enables POST /api/auth/google and the id token audience check",
+	GOOGLE_CLIENT_SECRET: "Google OAuth client secret for NextAuth sign-in",
+	APPLE_CLIENT_ID:
+		"Apple Services ID — enables POST /api/auth/apple and the identity token audience check",
+
 	// Application
 	APP_NAME: "Application name - used in metadata, emails, and page titles",
 	APP_DESCRIPTION:
@@ -221,6 +230,13 @@ function createEnvSchema(service) {
 				"NEXTAUTH_URL must be an absolute http(s) URL",
 			),
 
+			// OAuth (optional — each provider is inert unless its client id is set)
+			GITHUB_ID: optionalString,
+			GITHUB_SECRET: optionalString,
+			GOOGLE_CLIENT_ID: optionalString,
+			GOOGLE_CLIENT_SECRET: optionalString,
+			APPLE_CLIENT_ID: optionalString,
+
 			// Application
 			APP_NAME: optionalString,
 			APP_DESCRIPTION: optionalString,
@@ -416,6 +432,24 @@ function collectWarnings() {
 		);
 	}
 
+	// OAuth: half a provider is a provider that silently does not work.
+	// `auth.js` only registers a NextAuth provider when BOTH the client id and
+	// the secret are set, so an id with no secret leaves the sign-in button
+	// absent and the failure looks like a missing feature rather than a
+	// half-finished configuration. Worth saying out loud.
+	for (const [idKey, secretKey, label] of [
+		["GITHUB_ID", "GITHUB_SECRET", "GitHub"],
+		["GOOGLE_CLIENT_ID", "GOOGLE_CLIENT_SECRET", "Google"],
+	]) {
+		const hasId = Boolean(process.env[idKey]?.trim());
+		const hasSecret = Boolean(process.env[secretKey]?.trim());
+		if (hasId !== hasSecret) {
+			warnings.push(
+				`${label} OAuth is incomplete: set both ${idKey} and ${secretKey} to enable it. The sign-in button stays hidden until both are present.`,
+			);
+		}
+	}
+
 	// Umami pair completeness
 	const umamiUrl = process.env.NEXT_PUBLIC_UMAMI_URL?.trim();
 	const umamiWebsiteId = process.env.NEXT_PUBLIC_UMAMI_WEBSITE_ID?.trim();

package/templates/mobile/.env.example

@@ -10,7 +10,14 @@ EXPO_PUBLIC_API_URL=http://localhost:3000
 # --- Google OAuth (Optional) ---
 # Get credentials at: https://console.cloud.google.com/apis/credentials
 # EXPO_PUBLIC_GOOGLE_CLIENT_ID=your_google_client_id
+#
+# This must be the SAME client id the web app has as GOOGLE_CLIENT_ID. The
+# server compares it against the token's audience on every sign-in, so a
+# mismatch here fails the login with an "invalid token" error.
 
 # --- Apple Sign In (Optional) ---
 # Apple Sign In is configured via EAS and Apple Developer Console.
 # No environment variables needed - it uses native module configuration.
+#
+# The web app must have APPLE_CLIENT_ID set to your Services ID, or
+# POST /api/auth/apple refuses every request as unconfigured.