@usequark/quark-create-app 1.25.6 → 1.25.8

package/package.json

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

package/src/deploy/adapters/iac.js

@@ -106,6 +106,7 @@ export async function generateIacFile({
 	variableRefs = {},
 	serviceVars = {},
 	projectName = "quark-app",
+	provision = true,
 }) {
 	const { default: fs } = await import("fs-extra");
 	const { dirname } = await import("node:path");
@@ -167,7 +168,83 @@ export async function generateIacFile({
 		);
 	}
 
-	const resources = services.map((s) => toIdentifier(s.name)).join(", ");
+	// `postgres` and `redis` are dedicated helpers; anything else falls back to
+	// the generic `database` helper. Both are already in IAC_HELPERS, so the
+	// import list picks them up automatically.
+	const DATABASE_HELPERS = { Postgres: "postgres", Redis: "redis" };
+
+	// Declare every database the services reference, so a whole-project apply
+	// does not plan to delete it.
+	//
+	// Railway treats an omitted resource in a single-file project as absent, and
+	// absent means delete: "One project definition, one apply, and omitting a
+	// resource means deleting it." The databases are provisioned out-of-band by
+	// `ensurePlugin()` (`railway add --database`), then referenced here via
+	// `${{Postgres.DATABASE_URL}}`. Without this block a second deploy plans to
+	// destroy the databases the first one created.
+	//
+	// When `provision` is false (`--no-provision`), we must distinguish two
+	// cases:
+	//
+	// 1. A fresh project that has never been provisioned: no databases should be
+	//    declared, because declaring them would provision them on the next apply
+	//    — exactly what the user opted out of.
+	//
+	// 2. An existing project whose databases were provisioned by an earlier
+	//    deploy: those databases are already managed by this file. Removing
+	//    their declarations would make `railway config apply` delete them,
+	//    because omitted resources are deletions. So we preserve any database
+	//    that the existing file already declares, and only suppress declarations
+	//    that would be new.
+	let previousContent = null;
+	try {
+		previousContent = await fs.readFile(iacPath, "utf8");
+	} catch {
+		previousContent = null;
+	}
+
+	const serviceIdentifiers = new Set(services.map((s) => toIdentifier(s.name)));
+	const databaseNames = new Set();
+	const referencePattern = /\$\{\{([A-Za-z_][\w]*)\.([A-Za-z_][\w]*)\}\}/g;
+
+	for (const value of Object.values(variableRefs)) {
+		for (const match of String(value).matchAll(referencePattern)) {
+			if (!serviceIdentifiers.has(match[1])) {
+				databaseNames.add(match[1]);
+			}
+		}
+	}
+
+	if (!provision) {
+		// Preserve databases the existing file already declares; suppress only
+		// declarations that would be new. When there is no existing file, no
+		// databases are already declared, so all are suppressed.
+		for (const dbName of [...databaseNames]) {
+			const alreadyDeclared =
+				previousContent !== null &&
+				new RegExp(
+					`\\b${DATABASE_HELPERS[dbName] ?? "database"}\\s*\\(\\s*["']${escapeTsString(dbName)}["']`,
+				).test(previousContent);
+			if (!alreadyDeclared) {
+				databaseNames.delete(dbName);
+			}
+		}
+	}
+
+	const sortedDatabases = [...databaseNames].sort();
+
+	for (const dbName of sortedDatabases) {
+		const helper = DATABASE_HELPERS[dbName] ?? "database";
+		const dbIdentifier = `${toIdentifier(dbName)}Db`;
+		resourceLines.push(
+			`\tconst ${dbIdentifier} = ${helper}("${escapeTsString(dbName)}");`,
+		);
+	}
+
+	const resources = [
+		...services.map((s) => toIdentifier(s.name)),
+		...sortedDatabases.map((name) => `${toIdentifier(name)}Db`),
+	].join(", ");
 
 	const body = `export default defineRailway(() => {
 ${resourceLines.join("\n\n")}

package/src/deploy/deploy.js

@@ -181,6 +181,7 @@ export async function deployToRailway(options = {}) {
 		services: discovery.services,
 		// Pass raw name — generateIacFile handles escaping internally
 		projectName: projectLabel,
+		provision,
 		variableRefs: {
 			// Quoted: these land inside generated TypeScript as object values,
 			// where `${{...}}` must be a string literal to parse at all. The

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

@@ -23,6 +23,21 @@ 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 — with no client
+# id, the matching route refuses every request with 503. Server-only: do not
+# prefix them with NEXT_PUBLIC_.
+#
+# APPLE_CLIENT_ID accepts a comma-separated list: Apple identity tokens carry
+# either the bundle identifier (native iOS) or the Services ID (web flow) as
+# their `aud` claim, so set both to accept either.
+# 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/.railway/railway.ts

@@ -1,4 +1,4 @@
-import { defineRailway, preserve, project, service } from "railway/iac";
+import { defineRailway, postgres, preserve, project, redis, service } from "railway/iac";
 
 export default defineRailway(() => {
 	const web = service("web", {
@@ -34,7 +34,10 @@ export default defineRailway(() => {
 		},
 	});
 
+	const PostgresDb = postgres("Postgres");
+	const RedisDb = redis("Redis");
+
 	return project("__QUARK_PROJECT_NAME__", {
-		resources: [web, worker],
+		resources: [web, worker, PostgresDb, RedisDb],
 	});
 });

package/templates/base-project/DEPLOYMENT.md

@@ -0,0 +1,39 @@
+# Deployment Guide
+
+## Railway
+
+### 1. Push to GitHub
+
+```bash
+gh repo create your-project-name --private --source=. --push
+```
+
+No `gh` CLI? Go to [github.com/new](https://github.com/new), create the repo, then:
+
+```bash
+git remote add origin https://github.com/your-username/your-project-name.git
+git push -u origin main
+```
+
+### 2. Deploy on Railway
+
+1. Go to [railway.app](https://railway.app) → **New Project** → **Deploy from GitHub repo** → select `your-project-name`
+2. In the service → **Settings** → **Source**:
+   - Set **Root Directory** to `/` (the repo root - Railpack needs the full monorepo context to resolve workspace dependencies)
+3. In the project → **+ New** → **Database** → **Add PostgreSQL**
+4. In the project → **+ New** → **Database** → **Add Redis**
+5. Use `.env.railway.example` as the default Railway variable set:
+   - Copy the non-service defaults into Railway shared variables or each service's variables as your starting point
+   - Wire `DATABASE_URL` and `REDIS_URL` with Railway service references or paste the managed service connection strings Railway provides
+   - Replace `NEXTAUTH_SECRET`, `APP_URL`, and `ADMIN_PASSWORD`
+   - `HOSTNAME=0.0.0.0` is included so the standalone Next server binds correctly on Railway
+   - Apply `DATABASE_URL`, `REDIS_URL`, `STORAGE_PROVIDER`, and `WORKER_CONCURRENCY` to the worker too if you deploy it
+6. *(If you included the worker)* **+ New** → **GitHub Repo** → same repo → **Root Directory** → `/`
+
+Railway auto-deploys on every push to `main`. Migrations run automatically before each deploy via `preDeploy` in `.railway/railway.ts`.
+
+If you need to seed Railway manually after the first migration, run `SEED_PROFILE=minimal pnpm db:seed` inside a Railway shell/one-off command, or from a machine using Railway's externally reachable database credentials, and provide the required admin credentials. The seed guard rejects remote seeds without an explicit profile on purpose.
+
+> **Important:** Root Directory must be `/` (not `apps/web`) so Railpack can resolve pnpm workspace dependencies. The `.railway/railway.ts` file defines all service configuration via Infrastructure as Code.
+>
+> Railway starts the web service with `HOSTNAME=0.0.0.0 pnpm --dir apps/web start:deploy` (configured in `.railway/railway.ts`), which delegates to the standalone entrypoint `node .next/standalone/apps/web/server.js`. This forces the standalone Next server to bind on Railway's network interface. The `pnpm start` script uses `next start` which requires full `node_modules` - it's for local testing only.

package/templates/base-project/README.md

@@ -1,164 +1,85 @@
-# __QUARK_PROJECT_NAME__
+<p align="center">
+  <img src="apps/web/public/quark.svg" alt="__QUARK_PROJECT_NAME__" width="120" />
+</p>
 
-Scaffolded with [Quark](https://github.com/usequark/quark) on __QUARK_SCAFFOLD_DATE__.
+<p align="center">
+  <strong>__QUARK_PROJECT_BRIEF__</strong>
+</p>
 
-## Start Here
+<p align="center">
+  <img src="https://img.shields.io/badge/Node.js-22-339933?style=flat&logo=node.js&logoColor=white" alt="Node.js 22" />
+  <img src="https://img.shields.io/badge/Next.js-16-000000?style=flat&logo=next.js&logoColor=white" alt="Next.js 16" />
+  <img src="https://img.shields.io/badge/Prisma-7-2D3748?style=flat&logo=prisma&logoColor=white" alt="Prisma 7" />
+</p>
 
-- `docs/START_HERE.md` - current onboarding path for this project
-- `docs/FIRST_FEATURE.md` - add your first domain model, query helper, and page
-- `.opencode/skills/` - embedded skills (add a model, endpoint, dashboard, or build a booking/CRM/CMS/AI system)
-- `CLAUDE.md` - AI tool context for Claude Code, Cursor, Copilot, and others
+---
 
-## Local Development
+## Quick Start
 
 ```bash
-docker compose up -d   # Start PostgreSQL, Redis, Mailpit
-pnpm install           # Install dependencies
-pnpm db:migrate        # Apply migrations
-pnpm db:seed           # Seed the database (admin user + sample data)
-pnpm dev               # Start the app (and worker, if included)
+pnpm install
+docker compose up -d
+pnpm db:migrate
+pnpm dev
 ```
 
 Open [http://localhost:__QUARK_WEB_PORT__](http://localhost:__QUARK_WEB_PORT__)
 
-## UI References
+## Services
 
-- `apps/web/src/app/page.js` - production-style public page built from the shared UI package
-- `packages/ui/README.md` - supported component surface and props
-
-## Included in This Project
-
-| Area | Status | Where to start |
-|---|---|---|
-| Web app | Included | `apps/web/src/app/` |
-| Database | Included | `packages/db/prisma/schema.prisma` |
-| Config | Included | `packages/config/src/load-config.js` |
-__QUARK_FEATURE_ROWS__
-
-Optional features can be added later with:
+| Service    | Description                | Port(s)            |
+| ---------- | -------------------------- | ------------------ |
+| PostgreSQL | Database                   | `5432`             |
+| Redis      | Cache & job queue          | `6379`             |
+| Mailpit    | Local SMTP / email viewer  | `1025` / `8025`    |
 
 ```bash
-npx @usequark/quark-create-app add <feature>
+docker compose up -d   # start all services
+docker compose down    # stop all services
 ```
 
-### PWA (Optional)
-
-When enabled, your app includes:
-- `src/app/manifest.json` — web app manifest for installability (served natively by Next.js)
-- `public/sw.js` — vanilla service worker with cache-first static assets and network-first navigation
-- `src/app/_components/PWARegister.js` — client component that registers the SW in production
-
-Edit `manifest.json` to set your app name, theme color, and icons.
-The service worker uses standard Web APIs with no external dependencies.
-
-## First Files to Edit
-
-- `packages/db/prisma/schema.prisma` - add your domain models
-- `packages/db/src/queries.js` - add reusable query helpers
-- `apps/web/src/app/` - build pages, Server Actions, and route handlers
-__QUARK_FIRST_EDITS__
-
-## Feature Guides
-
-- `docs/FIRST_FEATURE.md` - the best first walkthrough for product work
-- `packages/db/src/queries.js` - the canonical place for reusable data access
-__QUARK_FEATURE_GUIDES__
-
-## Database
-
-| Task | Command |
-|------|---------|
-| Run migrations | `pnpm db:migrate` |
-| Push schema (no migration) | `pnpm db:push` |
-| Generate Prisma client | `pnpm db:generate` |
-| Seed database | `pnpm db:seed` |
-| Open Prisma Studio | `pnpm db:studio` |
-
-## Other Commands
+## Development
 
 ```bash
-pnpm build    # Build all packages
-pnpm test     # Run all tests (requires Docker)
-pnpm lint     # Lint + format check (Biome)
-pnpm clean:check  # Review reclaimable build artifacts
-pnpm clean        # Remove local build artifacts
-pnpm clean:deep   # Also remove repo-local temp workspaces
-QUARK_SKIP_AUTO_CLEAN=1 pnpm dev  # Disable dev auto-clean for this run
-npx @usequark/quark-create-app update --scaffold-check                 # Review scaffold-managed drift
-npx @usequark/quark-create-app update --scaffold-check --fail-on-drift # CI-friendly drift check
+pnpm build   # Build all packages
+pnpm test    # Run tests
+pnpm lint    # Lint & format (Biome)
 ```
 
-## Launch
-
-### 1. Push to GitHub
+## Database
 
-```bash
-gh repo create __QUARK_PROJECT_NAME__ --private --source=. --push
-```
+| Task                       | Command             |
+| -------------------------- | ------------------- |
+| Run migrations             | `pnpm db:migrate`   |
+| Push schema (no migration) | `pnpm db:push`      |
+| Generate Prisma client     | `pnpm db:generate`  |
+| Seed database              | `pnpm db:seed`      |
+| Open Prisma Studio         | `pnpm db:studio`    |
 
-No `gh` CLI? Go to [github.com/new](https://github.com/new), create the repo, then:
+## Project Structure
 
-```bash
-git remote add origin https://github.com/<you>/__QUARK_PROJECT_NAME__.git
-git push -u origin main
+```
+__QUARK_PROJECT_NAME__/
+apps/
+  web/        → Next.js 16 (App Router, Server Actions)
+__QUARK_OPTIONAL_APPS__packages/
+  config/     → Shared environment & app configuration
+  db/         → Prisma schema, migrations & queries
+__QUARK_OPTIONAL_PACKAGES__
 ```
 
-> **Nested inside an existing repository?** GitHub Actions only reads workflow
-> files from the repository root, so this project's `.github/workflows/*.yml`
-> will be ignored. Copy them into the parent repository's
-> `.github/workflows/` and add `working-directory: <path-to-this-project>` to
-> each job's steps (plus path filters so the workflows only run on changes in
-> this directory).
-
-### 2. Deploy on Railway
-
-> **One-click Railway template coming soon.** For now, follow these steps:
-
-1. Go to [railway.app](https://railway.app) → **New Project** → **Deploy from GitHub repo** → select `__QUARK_PROJECT_NAME__`
-2. In the service → **Settings** → **Source**:
-   - Set **Root Directory** to `/` (the repo root - Railpack needs the full monorepo context to resolve workspace dependencies)
-3. In the project → **+ New** → **Database** → **Add PostgreSQL**
-4. In the project → **+ New** → **Database** → **Add Redis**
-5. Use `.env.railway.example` as the default Railway variable set:
-   - Copy the non-service defaults into Railway shared variables or each service's variables as your starting point
-   - Wire `DATABASE_URL` and `REDIS_URL` with Railway service references or paste the managed service connection strings Railway provides
-   - Replace `NEXTAUTH_SECRET`, `APP_URL`, and `ADMIN_PASSWORD`
-   - `HOSTNAME=0.0.0.0` is included so the standalone Next server binds correctly on Railway
-   - Apply `DATABASE_URL`, `REDIS_URL`, `STORAGE_PROVIDER`, and `WORKER_CONCURRENCY` to the worker too if you deploy it
-6. *(If you included the worker)* **+ New** → **GitHub Repo** → same repo → **Root Directory** → `/`
-
-Railway auto-deploys on every push to `main`. Migrations run automatically before each deploy via `preDeploy` in `.railway/railway.ts`.
-
-If you need to seed Railway manually after the first migration, run `SEED_PROFILE=minimal pnpm db:seed` inside a Railway shell/one-off command, or from a machine using Railway's externally reachable database credentials, and provide the required admin credentials. The seed guard rejects remote seeds without an explicit profile on purpose.
-
-> **Important:** Root Directory must be `/` (not `apps/web`) so Railpack can resolve pnpm workspace dependencies. The `.railway/railway.ts` file defines all service configuration via Infrastructure as Code.
->
-> Railway starts the web service with `HOSTNAME=0.0.0.0 pnpm --dir apps/web start:deploy` (configured in `.railway/railway.ts`), which delegates to the standalone entrypoint `node .next/standalone/apps/web/server.js`. This forces the standalone Next server to bind on Railway's network interface. The `pnpm start` script uses `next start` which requires full `node_modules` - it's for local testing only.
-
-## AI-Assisted Development
-
-This project ships with pre-loaded context for Claude Code, Cursor, GitHub Copilot, and others - see `CLAUDE.md` for the full reference.
-
-**Suggested first prompt:**
+## Tech Stack
 
-> I'm building __QUARK_PROJECT_NAME__ - [describe what your app does in one sentence].
->
-> Start by reviewing `CLAUDE.md` so you understand the full stack, then:
-> 1. Add the Prisma models we need to `packages/db/prisma/schema.prisma`
-> 2. Create the query helpers in `packages/db/src/queries.js`
-> 3. Build the first page in `apps/web/src/app/` using our UI component system
+- **Framework** - Next.js 16 (React 19)
+- **Styling** - Tailwind CSS 4
+- **Database** - PostgreSQL 16 + Prisma 7
+- **Queue** - Redis 7 (BullMQ)
+- **Auth** - NextAuth.js v5
+- **Monorepo** - pnpm workspaces + Turborepo
+- **Linting** - Biome
 
-Replace that bracketed description with what you're actually building, and the AI has everything it needs.
+## Deployment
 
-## Structure
+See [DEPLOYMENT.md](DEPLOYMENT.md) for Railway setup instructions.
 
-```
-__QUARK_PROJECT_NAME__/
-├── apps/
-│   ├── web/         # Next.js 16 (App Router, Server Actions)
-__QUARK_OPTIONAL_APPS__├── packages/
-│   ├── db/          # Prisma schema + query helpers
-│   └── config/      # Environment validation
-├── docker-compose.yml
-└── CLAUDE.md        # AI tool context - keep this updated
-```
+<!-- Scaffolded with Quark on __QUARK_SCAFFOLD_DATE__ -->

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

@@ -26,11 +26,35 @@ 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 bind tokens to — with no
+# client id, the matching route refuses every request with 503 rather than
+# exchanging a token it cannot bind to this deployment.
+#
+# 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 POST /api/auth/google checks on
+# every sign-in, so a mismatch with the mobile app fails the login.
+# 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 token audience POST /api/auth/apple checks on every sign-in. No secret is
+# involved - that route verifies the signed identity token itself.
+#
+# Apple identity tokens carry *either* the bundle identifier (native iOS) *or*
+# the Services ID (web flow) as their `aud` claim, depending on which flow the
+# client uses. Set both, comma-separated, to accept either:
+#   APPLE_CLIENT_ID=com.example.web, com.example.app
+# A single value works too if you only use one flow.
+# 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/auth/apple/route.js

@@ -1,3 +1,5 @@
+import { createHash, timingSafeEqual } from "node:crypto";
+import { getAppleClientIds } from "@usequark/quark-config/oauth";
 import { validateBody } from "@usequark/quark-core";
 import { user } from "@usequark/quark-db";
 import { importJWK, jwtVerify } from "jose";
@@ -8,18 +10,44 @@ import { handleError } from "../../error-handler";
 
 const appleAuthSchema = z.object({
 	identityToken: z.string().min(1),
-	nonce: z.string().optional(),
+	nonce: z.string().min(1),
 });
 
 const APPLE_KEYS_URL = "https://appleid.apple.com/auth/keys";
 
+/**
+ * SHA-256 of a UTF-8 string, lowercase hex — the same digest the mobile client
+ * computes before handing it to Apple as the sign-in nonce.
+ *
+ * @param {string} value
+ * @returns {string}
+ */
+function sha256Hex(value) {
+	return createHash("sha256").update(value, "utf8").digest("hex");
+}
+
 /**
  * POST /api/auth/apple
  * Verify Apple identity token and issue a custom JWT.
  */
 export async function POST(request) {
 	try {
-		const { identityToken } = await validateBody(request, appleAuthSchema);
+		const clientIds = getAppleClientIds();
+
+		// Fail closed when unconfigured. This route is public, so an unconfigured
+		// deployment must not keep authenticating people — see the note in the
+		// Google route for the full reasoning.
+		if (!clientIds) {
+			return NextResponse.json(
+				{ message: "Apple sign-in is not configured on this server" },
+				{ status: 503 },
+			);
+		}
+
+		const { identityToken, nonce } = await validateBody(
+			request,
+			appleAuthSchema,
+		);
 
 		// Decode the JWT header to get the kid
 		const [headerB64] = identityToken.split(".");
@@ -38,13 +66,21 @@ export async function POST(request) {
 			);
 		}
 
-		// Verify the token using Apple's public key
+		// Verify the token using Apple's public key. `audience` is what binds the
+		// identity token to this app: without it, an identity token Apple issued
+		// to a different bundle or service id for the same Apple ID verifies fine
+		// and would be exchanged for a first-party session.
+		//
+		// Apple identity tokens can carry *either* the bundle identifier (native
+		// iOS) *or* the Services ID (web flow) as their `aud` claim, depending on
+		// which flow the client uses. Passing both accepts either.
 		const publicKey = await importJWK(matchingKey, "RS256");
 
 		let payload;
 		try {
 			const result = await jwtVerify(identityToken, publicKey, {
 				issuer: "https://appleid.apple.com",
+				audience: clientIds,
 			});
 			payload = result.payload;
 		} catch {
@@ -54,6 +90,30 @@ export async function POST(request) {
 			);
 		}
 
+		// The nonce is Apple's replay defence. The client sends a raw nonce and
+		// hands Apple its SHA-256 digest; Apple returns that digest in the token's
+		// `nonce` claim. Re-hashing what we received is what proves this token was
+		// minted for *this* sign-in attempt rather than lifted from an earlier one.
+		//
+		// Both halves must be present. A token with no `nonce` claim proves nothing
+		// about which attempt it came from, so treating "the client sent no nonce" as
+		// "skip the check" would leave the replay window open to any caller who
+		// simply omits the field.
+		if (typeof payload.nonce !== "string" || payload.nonce === "") {
+			return NextResponse.json(
+				{ message: "Invalid Apple token" },
+				{ status: 401 },
+			);
+		}
+
+		const expectedNonce = sha256Hex(nonce);
+		if (!safeEqualStrings(expectedNonce, payload.nonce)) {
+			return NextResponse.json(
+				{ message: "Invalid Apple token" },
+				{ status: 401 },
+			);
+		}
+
 		const appleEmail = payload.email;
 		if (!appleEmail) {
 			return NextResponse.json(
@@ -80,3 +140,21 @@ export async function POST(request) {
 		return handleError(error);
 	}
 }
+
+/**
+ * Constant-time string comparison.
+ *
+ * `timingSafeEqual` throws when the two buffers differ in length, so the length
+ * check has to come first. It short-circuits on length — which is fine, because
+ * both sides are fixed-length hex digests here, so length is not a secret.
+ *
+ * @param {string} a
+ * @param {string} b
+ * @returns {boolean}
+ */
+function safeEqualStrings(a, b) {
+	const aBuf = Buffer.from(a, "utf8");
+	const bBuf = Buffer.from(b, "utf8");
+	if (aBuf.length !== bBuf.length) return false;
+	return timingSafeEqual(aBuf, bBuf);
+}

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

@@ -1,3 +1,7 @@
+import {
+	getGoogleClientId,
+	isAudienceValid,
+} from "@usequark/quark-config/oauth";
 import { validateBody } from "@usequark/quark-core";
 import { user } from "@usequark/quark-db";
 import { NextResponse } from "next/server";
@@ -17,6 +21,21 @@ const GOOGLE_TOKENINFO_URL = "https://oauth2.googleapis.com/tokeninfo";
  */
 export async function POST(request) {
 	try {
+		const clientId = getGoogleClientId();
+
+		// Fail closed when unconfigured. This route is public — it does not need
+		// your frontend to call it, or anyone to have set up Google sign-in — so
+		// "nobody configured it" is not a reason to keep serving. Without a client
+		// id there is no audience to compare `tokeninfo.aud` against, and a route
+		// that skips the comparison accepts any token Google ever issued to any
+		// app for this address. Refusing is the only safe default.
+		if (!clientId) {
+			return NextResponse.json(
+				{ message: "Google sign-in is not configured on this server" },
+				{ status: 503 },
+			);
+		}
+
 		const { idToken } = await validateBody(request, googleAuthSchema);
 
 		// Verify the token with Google's tokeninfo endpoint
@@ -33,6 +52,19 @@ export async function POST(request) {
 
 		const tokenInfo = await tokenInfoResponse.json();
 
+		// The audience is the OAuth client id the token was minted for. Google
+		// verified the signature; it did not verify the token was for *this* app. A
+		// token Google issued to a different app for the victim's address is
+		// genuine and correctly signed, and must still be refused — otherwise
+		// anyone who can get the victim to sign in to any Google app at all can log
+		// in as them here.
+		if (!isAudienceValid(tokenInfo.aud, clientId)) {
+			return NextResponse.json(
+				{ message: "Invalid Google token" },
+				{ status: 401 },
+			);
+		}
+
 		const googleEmail = tokenInfo.email;
 		if (!googleEmail) {
 			return NextResponse.json(

package/templates/base-project/scripts/doctor.js

@@ -221,6 +221,42 @@ if (exampleContent) {
 	}
 }
 
+// ── Check S6: README branding block is still the Quark default ───────────────
+{
+	const readmeForBranding = read("README.md");
+	if (readmeForBranding) {
+		const staleBranding = [];
+
+		// The scaffold ships the Quark mark as a stand-in logo; it resolves
+		// (unlike a missing file) but it is Quark's brand, not the user's.
+		if (/src="[^"]*quark\.svg"/i.test(readmeForBranding)) {
+			staleBranding.push(
+				"README.md → logo still points at apps/web/public/quark.svg (the Quark mark)",
+			);
+		}
+
+		// Mirrors the S5 heuristic: a tagline that is only "<name> application"
+		// is the default the CLI seeds from the project name, not a real one.
+		const tagline =
+			readmeForBranding.match(/<strong>(.*?)<\/strong>/)?.[1]?.trim() ?? "";
+		if (/\bapplication\b$/i.test(tagline) && tagline.split(/\s+/).length <= 3) {
+			staleBranding.push(
+				`README.md → tagline is still the scaffold default: "${tagline}"`,
+			);
+		}
+
+		if (staleBranding.length > 0) {
+			warn(
+				"readme-branding",
+				"branding",
+				"README branding block is still the Quark default",
+				staleBranding.join("\n"),
+				"Swap apps/web/public/quark.svg for your own logo (keep the filename so the PWA icon keeps working) and rewrite the tagline to describe your app",
+			);
+		}
+	}
+}
+
 // ── Environment-dependent checks (skipped in CI mode) ─────────────────────────
 
 if (!CI) {
@@ -318,14 +354,22 @@ if (envContent && exampleContent) {
 
 // ── Check E7: README still contains Quark template content ───────────────────
 const readmeContent = read("README.md");
-if (readmeContent && /quark/i.test(readmeContent)) {
-	info(
-		"readme",
-		"documentation",
-		"README.md still contains references to Quark",
-		"README.md",
-		"Update the README to describe your own project",
-	);
+if (readmeContent) {
+	// Strip the invisible scaffold-metadata comment and the default logo src -
+	// check S6 owns the branding block. What is left is Quark references the
+	// author actually wrote into the README content.
+	const visibleReadme = readmeContent
+		.replace(/<!--[\s\S]*?-->/g, "")
+		.replace(/src="[^"]*quark\.svg"/gi, "");
+	if (/quark/i.test(visibleReadme)) {
+		info(
+			"readme",
+			"documentation",
+			"README.md still contains references to Quark",
+			"README.md",
+			"Update the README to describe your own project",
+		);
+	}
 }
 
 } // end if (!CI)

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 {
+	getAppleClientIds,
+	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,124 @@
+/**
+ * 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;
+}
+
+/**
+ * Splits a comma-separated audience list into individual ids, trimming each
+ * and dropping blanks. Returns undefined when the whole value is blank.
+ *
+ * @param {string | undefined} value
+ * @returns {string[] | undefined}
+ */
+function readClientIdList(value) {
+	const ids = (value ?? "")
+		.split(",")
+		.map((id) => id.trim())
+		.filter(Boolean);
+	return ids.length > 0 ? ids : 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 OAuth audience(s), or undefined when Apple sign-in is not configured.
+ *
+ * Apple identity tokens can carry *either* the bundle identifier (native iOS)
+ * *or* the Services ID (web flow) as their `aud` claim — which one depends on
+ * how the client was registered and which flow it uses. A single-value audience
+ * would reject one of the two, so this returns a list.
+ *
+ * @returns {string[] | undefined}
+ */
+export function getAppleClientIds() {
+	return readClientIdList(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(getAppleClientIds());
+}
+
+/**
+ * Compares a token's `aud` claim against the expected client id(s).
+ *
+ * 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.
+ *
+ * Accepts either a single id or an array. For Apple, pass the full list from
+ * `getAppleClientIds()` so both the bundle identifier and the Services ID are
+ * accepted.
+ *
+ * @param {unknown} actual - The `aud` claim from the verified token.
+ * @param {string | string[] | undefined} expected - The configured client id(s).
+ * @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 (Array.isArray(expected)) {
+		if (expected.length === 0) return false;
+		return expected.includes(actual);
+	}
+
+	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,18 @@ 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, or POST /api/auth/apple
+# refuses every request as unconfigured. It takes a comma-separated
+# list of audiences, and native iOS identity tokens carry the bundle
+# identifier from app.json as their audience (the Services ID applies
+# to web-flow tokens only) - so include the bundle identifier here, or
+# every native sign-in fails with 401.