@usequark/quark-create-app 1.25.6 → 1.25.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usequark/quark-create-app",
-  "version": "1.25.6",
+  "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/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.