@mars-stack/cli 7.0.3 → 7.0.5

package/README.md

@@ -36,6 +36,7 @@ mars create my-app
 ### `mars add feature <name>`
 
 Generate a feature module at `src/features/<name>/` with:
+
 - `server/index.ts` -- typed CRUD operations with `import 'server-only'`
 - `types.ts` -- Zod validation schemas and TypeScript types
 
@@ -121,6 +122,18 @@ mars upgrade           # upgrade to latest
 mars upgrade --dry-run # preview what would change
 ```
 
+### `mars template sync`
+
+Copy upstream **template plumbing** (scripts, auth shell files, and other manifest-listed paths) from the CLI-bundled template into an **existing** Mars project. Requires `.mars/scaffold.json` at the project root (from `mars create`); exits with an error if missing.
+
+```bash
+mars template sync --dry-run              # list planned changes, no writes
+mars template sync                        # default: plumbing category only
+mars template sync --only user-owned --force  # overwrite user-owned paths too (backups under .mars/backups/)
+```
+
+**vs `mars upgrade`:** `mars upgrade` bumps Mars npm packages only — it does **not** re-copy template source files. Use `mars template sync` when a CLI release includes fixes to `ensure-db.mjs`, proxy, or other synced paths. See the Mars monorepo [scaffold-template-sync-upgrade](https://github.com/greaveselliott/mars/blob/main/docs/exec-plans/active/scaffold-template-sync-upgrade.md) exec plan for the safety model and path inventory.
+
 ### `mars telemetry <enable|disable>`
 
 Opt in or out of anonymous usage analytics. Stored in `~/.marsrc`. Tracks command usage and feature selections only -- never project names, file contents, or env vars.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mars-stack/cli",
-  "version": "7.0.3",
+  "version": "7.0.5",
   "description": "MARS CLI: scaffold, configure, and maintain SaaS apps",
   "license": "MIT",
   "repository": {

package/template/AGENTS.md

@@ -64,10 +64,12 @@ src/
 5. **Parse data at the boundary** — Zod validation on every API route input.
 6. **User-scoped queries use session userId** — Never accept userId from request params for authorization.
 7. **Constant-time comparison for secrets** — Use `constantTimeEqual` from `@mars-stack/core`, never `===`.
+8. **CSRF on client mutations** — Spread `getCSRFHeaders()` from `useCSRFContext()` into mutating `fetch` calls to `/api/*` (see `src/proxy.ts` for exemptions). On error responses, use `readApiError` from `@/lib/read-api-error` instead of blind `response.json()` so plain-text 403 bodies do not throw `SyntaxError`.
 
 ## Config
 
 `src/config/app.config.ts` is the single source of truth for:
+
 - App identity (name, URL, support email)
 - Feature flags (auth, admin, billing, notifications, etc.)
 - Service providers (email, storage, database, payments, etc.)
@@ -78,7 +80,7 @@ src/
 ```bash
 yarn dev              # ensure-db (embedded Postgres) + Next.js — use this, not raw next dev
 yarn build            # Production build
-yarn test             # Run Vitest unit tests
+yarn test             # Vitest + CSRF client fetch guard (`scripts/check-csrf-client-fetch.mjs`)
 yarn test:e2e         # Run Playwright e2e tests
 yarn lint             # ESLint
 yarn db:push          # Push Prisma schema to database
@@ -91,6 +93,19 @@ yarn db:studio        # Open Prisma Studio
 
 **Email verification (local):** With console email, after register you land on `/verify` and use **“Click here to verify your email”** (no inbox needed). Set `AUTO_VERIFY_EMAIL=true` to skip that for **new** signups instead. `AUTO_VERIFY_EMAIL` applies when `yarn dev` runs or `APP_URL` points at `localhost` / `127.0.0.1`; ignored on Vercel production. Older accounts stay unverified until you use the link or Prisma Studio.
 
+## Updating scaffold plumbing (`mars template sync`)
+
+When you install a newer **`@mars-stack/cli`**, pull upstream template fixes into this repo with **`mars template sync`** from the project root (requires `.mars/scaffold.json` from `mars create`). If that file is missing, the CLI reports that the directory is not a Mars scaffold — you cannot sync a non-Mars project.
+
+- **`mars template sync --dry-run`** — print the planned file operations; no writes.
+- **Default** — sync **plumbing** paths from the bundled template manifest (scripts, shared shell, etc.).
+- **`--force`** — also apply **user-owned** manifest entries; previous files are copied to **`.mars/backups/<timestamp>/`** before overwrite. Use when you deliberately want upstream versions of those paths.
+- **`--only <category>`** — e.g. `plumbing` or `user-owned` (latter typically with `--force`).
+
+Deep context: [scaffold-template-sync-upgrade](https://github.com/greaveselliott/mars/blob/main/docs/exec-plans/active/scaffold-template-sync-upgrade.md) in the Mars monorepo (path inventory and safety model). Skill for agents: [.cursor/skills/mars-upgrade-scaffold/](.cursor/skills/mars-upgrade-scaffold/).
+
+**vs `mars upgrade`:** `mars upgrade` only bumps Mars **npm** packages and reinstalls — it does **not** re-copy template files. Use template sync when plumbing (e.g. `ensure-db.mjs`) changed in a CLI release.
+
 ## Working Discipline
 
 1. **Commit after every step.** When executing a plan, commit after each completed task — not at the end. Version control is the progress log. Each commit message should reference the plan and step (e.g., `feat(billing): add Subscription model (billing-plan step 1.1)`).
@@ -103,6 +118,7 @@ After **generator changes**, **template sync**, or before a **release**, run the
 
 ## Pointers
 
+- **Updating your app:** [README.md](README.md) — entry point; this section and `mars template sync` above.
 - **Architecture details:** [docs/design-docs/](docs/design-docs/)
 - **Core beliefs:** [docs/design-docs/core-beliefs.md](docs/design-docs/core-beliefs.md)
 - **Conversation feedback:** [docs/design-docs/conversation-as-system-record.md](docs/design-docs/conversation-as-system-record.md)

package/template/README.md

@@ -0,0 +1,30 @@
+# Mars application template
+
+This directory is the **Next.js app template** copied by `mars create` into a new project. In the Mars monorepo it is developed and tested here; published **`@mars-stack/cli`** bundles the same tree at release time.
+
+## Updating your Mars app
+
+After you upgrade **`@mars-stack/cli`** or want upstream fixes for scaffold **plumbing** (scripts, auth shell files, shared wiring listed in the sync manifest), run from your **project root**:
+
+```bash
+mars template sync --dry-run   # preview planned copies
+mars template sync             # apply (default: plumbing only)
+```
+
+**Requirements:** the project must be a Mars scaffold with **`.mars/scaffold.json`**. If that file is missing, the CLI exits with an error — this command does not apply to arbitrary Next.js repos.
+
+**Flags:**
+
+| Flag                | Meaning                                                                                                        |
+| ------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `--dry-run`         | Show what would change; no files written                                                                       |
+| `--force`           | Also sync **user-owned** manifest paths; always backs up replaced files under **`.mars/backups/<timestamp>/`** |
+| `--only <category>` | Limit to `plumbing` (default) or `user-owned` (usually with `--force`)                                         |
+
+**Safety:** Default sync overwrites **plumbing** files that the CLI owns (infrastructure). **User-owned** paths are skipped unless you pass **`--force`**, and overwrites are preceded by backups. Do not use `--force` on a dirty tree without reviewing `--dry-run` output.
+
+**Not `mars upgrade`:** `mars upgrade` bumps **`@mars-stack/core`** and **`@mars-stack/ui`** in `package.json` and reinstalls — it does **not** copy template source files. Use **both** commands when you need new package versions **and** refreshed plumbing (e.g. `scripts/ensure-db.mjs`).
+
+**Further reading (Mars monorepo):** [scaffold-template-sync-upgrade](https://github.com/greaveselliott/mars/blob/main/docs/exec-plans/active/scaffold-template-sync-upgrade.md) — full manifest, path inventory, and task history.
+
+**Agents:** see [.cursor/skills/mars-upgrade-scaffold/](.cursor/skills/mars-upgrade-scaffold/) and [AGENTS.md](AGENTS.md).

package/template/package.json

@@ -12,7 +12,7 @@
     "build": "prisma generate && next build",
     "start": "next start",
     "lint": "eslint .",
-    "test": "vitest run",
+    "test": "vitest run && node scripts/check-csrf-client-fetch.mjs",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "test:e2e": "playwright test",

package/template/scripts/check-csrf-client-fetch.mjs

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+/**
+ * Guard rail: client `fetch` to /api/ with mutating methods should include getCSRFHeaders()
+ * or a documented exemption (see template/src/proxy.ts csrfExemptRoutes).
+ *
+ * Run: node scripts/check-csrf-client-fetch.mjs (from template/)
+ */
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const srcRoot = join(__dirname, '..', 'src');
+
+const MUTATING = new Set(['POST', 'PUT', 'DELETE', 'PATCH']);
+
+/** Paths exempt from CSRF in proxy — keep in sync with template/src/proxy.ts */
+const EXEMPT_PATH_PREFIXES = [
+  '/api/csrf',
+  '/api/webhooks',
+  '/api/auth/verify',
+  '/api/auth/reset',
+];
+
+const IGNORED_DIRS = new Set(['node_modules', '.next']);
+
+function walk(dir, out) {
+  for (const name of readdirSync(dir)) {
+    if (IGNORED_DIRS.has(name)) continue;
+    const full = join(dir, name);
+    const st = statSync(full);
+    if (st.isDirectory()) walk(full, out);
+    else if (/\.(tsx|ts)$/.test(name) && !name.endsWith('.test.ts')) out.push(full);
+  }
+}
+
+function isExemptApiPath(urlExpr) {
+  const s = urlExpr.replace(/\s+/g, '');
+  for (const prefix of EXEMPT_PATH_PREFIXES) {
+    if (s.includes(`'${prefix}`) || s.includes(`\`${prefix}`) || s.includes(`"${prefix}`)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+const files = [];
+walk(srcRoot, files);
+
+let failures = 0;
+
+for (const file of files) {
+  const content = readFileSync(file, 'utf8');
+  const lines = content.split('\n');
+
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+    if (!line.includes('fetch(')) {
+      i += 1;
+      continue;
+    }
+
+    const start = i;
+    let depth = 0;
+    let j = i;
+    let block = '';
+    while (j < lines.length) {
+      const l = lines[j];
+      block += `${l}\n`;
+      for (const ch of l) {
+        if (ch === '(') depth += 1;
+        if (ch === ')') depth -= 1;
+      }
+      j += 1;
+      if (depth <= 0 && l.includes(')')) break;
+    }
+
+    const fetchBlock = block;
+    if (!fetchBlock.includes("'/api/") && !fetchBlock.includes('"/api/') && !fetchBlock.includes('`/api/')) {
+      i = j;
+      continue;
+    }
+
+    const methodMatch = fetchBlock.match(/method:\s*['"]([A-Z]+)['"]/);
+    const method = methodMatch?.[1];
+    if (!method || !MUTATING.has(method)) {
+      i = j;
+      continue;
+    }
+
+    const urlMatch = fetchBlock.match(/fetch\(\s*([^,)]+)/s);
+    const urlExpr = urlMatch?.[1]?.trim() ?? '';
+    if (isExemptApiPath(urlExpr)) {
+      i = j;
+      continue;
+    }
+
+    if (!fetchBlock.includes('getCSRFHeaders')) {
+      console.error(`${file}:${start + 1}: mutating fetch to /api/ without getCSRFHeaders()`);
+      failures += 1;
+    }
+
+    i = j;
+  }
+}
+
+if (failures > 0) {
+  console.error(`\ncheck-csrf-client-fetch: ${failures} issue(s). Add headers: { ...getCSRFHeaders() } or document proxy exemption.`);
+  process.exit(1);
+}
+
+console.log('check-csrf-client-fetch: OK');

package/template/src/__tests__/template-readme-contract.test.ts

@@ -0,0 +1,21 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const readmePath = join(__dirname, '../../README.md');
+
+/** MARS-046: user-facing template sync docs stay discoverable in copied scaffolds */
+describe('template README (mars template sync)', () => {
+  const content = readFileSync(readmePath, 'utf8');
+
+  it('documents dry-run, force, scaffold fingerprint, backups, and upgrade distinction', () => {
+    expect(content).toMatch(/`--dry-run`/);
+    expect(content).toMatch(/`--force`/);
+    expect(content).toMatch(/\.mars\/scaffold\.json/);
+    expect(content).toMatch(/\.mars\/backups/);
+    expect(content).toMatch(/`mars upgrade`/);
+    expect(content).toMatch(/mars template sync/);
+  });
+});

package/template/src/app/(auth)/forgotten-password/page.tsx

@@ -1,6 +1,7 @@
 'use client';
 
-import { useCSRF } from '@mars-stack/core/auth/hooks';
+import { readApiError } from '@/lib/read-api-error';
+import { useCSRFContext } from '@/lib/csrf-context';
 import { formSchemas } from '@mars-stack/core/auth/validation';
 import { useZodForm } from '@mars-stack/ui/hooks';
 import { Button, Input, Text } from '@mars-stack/ui';
@@ -9,7 +10,7 @@ import { routes } from '@/config/routes';
 import { useState } from 'react';
 
 export default function ForgottenPassword() {
-  const { getCSRFHeaders } = useCSRF();
+  const { getCSRFHeaders } = useCSRFContext();
   const [serverError, setServerError] = useState('');
   const [success, setSuccess] = useState(false);
   const [devLink, setDevLink] = useState<string | null>(null);
@@ -30,12 +31,12 @@ export default function ForgottenPassword() {
       });
 
       if (!response.ok) {
-        const data = await response.json();
-        setServerError(data.error || 'Failed to send reset email');
+        const { message } = await readApiError(response);
+        setServerError(message);
         return;
       }
 
-      const data = await response.json();
+      const data = (await response.json()) as { devLink?: string };
       if (data.devLink) {
         setDevLink(data.devLink);
       }

package/template/src/app/(auth)/register/page.tsx

@@ -1,7 +1,9 @@
 'use client';
 
 import { useAuth } from '@/features/auth/context/AuthContext';
-import { useCSRF, usePasswordStrength } from '@mars-stack/core/auth/hooks';
+import { useCSRFContext } from '@/lib/csrf-context';
+import { readApiError } from '@/lib/read-api-error';
+import { usePasswordStrength } from '@mars-stack/core/auth/hooks';
 import { formSchemas, type SignupFormData } from '@mars-stack/core/auth/validation';
 import { routes } from '@/config/routes';
 import { useZodForm } from '@mars-stack/ui/hooks';
@@ -13,7 +15,7 @@ import { Suspense, useEffect, useState } from 'react';
 function SignUpForm() {
   const router = useRouter();
   const { isAuthenticated, isLoading } = useAuth();
-  const { getCSRFHeaders, getCSRFFormData } = useCSRF();
+  const { getCSRFHeaders, getCSRFFormData } = useCSRFContext();
   const [serverError, setServerError] = useState('');
 
   useEffect(() => {
@@ -44,13 +46,14 @@ function SignUpForm() {
         body: JSON.stringify({ ...values, ...getCSRFFormData() }),
       });
 
-      const data = await response.json();
-
       if (!response.ok) {
-        setServerError(data.error || 'Failed to create account');
+        const { message } = await readApiError(response);
+        setServerError(message);
         return;
       }
 
+      const data = (await response.json()) as { devLink?: string };
+
       sessionStorage.setItem('verify-email', values.email);
       if (data.devLink) {
         sessionStorage.setItem('verify-dev-link', data.devLink);

package/template/src/app/(auth)/reset-password/page.tsx

@@ -1,6 +1,8 @@
 'use client';
 
-import { useCSRF, usePasswordStrength } from '@mars-stack/core/auth/hooks';
+import { readApiError } from '@/lib/read-api-error';
+import { useCSRFContext } from '@/lib/csrf-context';
+import { usePasswordStrength } from '@mars-stack/core/auth/hooks';
 import { formSchemas } from '@mars-stack/core/auth/validation';
 import { routes } from '@/config/routes';
 import { useZodForm } from '@mars-stack/ui/hooks';
@@ -12,7 +14,7 @@ import { Suspense, useState } from 'react';
 function ResetPasswordForm() {
   const searchParams = useSearchParams();
   const router = useRouter();
-  const { getCSRFHeaders } = useCSRF();
+  const { getCSRFHeaders } = useCSRFContext();
   const [serverError, setServerError] = useState('');
 
   const token = searchParams?.get('token') || '';
@@ -35,10 +37,9 @@ function ResetPasswordForm() {
         body: JSON.stringify(values),
       });
 
-      const data = await response.json();
-
       if (!response.ok) {
-        setServerError(data.error || 'Failed to reset password');
+        const { message } = await readApiError(response);
+        setServerError(message);
         return;
       }
 

package/template/src/app/(auth)/sign-in/page.tsx

@@ -1,7 +1,8 @@
 'use client';
 
-import { useAuth } from '@/features/auth/context/AuthContext';
-import { useCSRF } from '@mars-stack/core/auth/hooks';
+import { useAuth, type User } from '@/features/auth/context/AuthContext';
+import { readApiError } from '@/lib/read-api-error';
+import { useCSRFContext } from '@/lib/csrf-context';
 import { formSchemas, type LoginFormData } from '@mars-stack/core/auth/validation';
 import { routes } from '@/config/routes';
 import { useZodForm } from '@mars-stack/ui/hooks';
@@ -16,7 +17,7 @@ function SignInForm() {
   const { login, isAuthenticated, isLoading } = useAuth();
   const callbackUrl = searchParams?.get('callbackUrl') || routes.dashboard;
   const resetMessage = searchParams?.get('message');
-  const { getCSRFHeaders, getCSRFFormData } = useCSRF();
+  const { getCSRFHeaders, getCSRFFormData } = useCSRFContext();
   const [serverError, setServerError] = useState('');
 
   useEffect(() => {
@@ -38,13 +39,13 @@ function SignInForm() {
         body: JSON.stringify({ ...values, ...getCSRFFormData() }),
       });
 
-      const data = await response.json();
-
       if (!response.ok) {
-        setServerError(data.error || 'Failed to sign in');
+        const { message } = await readApiError(response);
+        setServerError(message);
         return;
       }
 
+      const data = (await response.json()) as { user?: User };
       if (data.user) login(data.user);
       router.push(callbackUrl);
     } catch {

package/template/src/app/(auth)/verify/[token]/page.tsx

@@ -1,5 +1,7 @@
 'use client';
 
+import { readApiError } from '@/lib/read-api-error';
+import { useCSRFContext } from '@/lib/csrf-context';
 import { routes } from '@/config/routes';
 import { LinkButton, Spinner, Text } from '@mars-stack/ui';
 import Link from 'next/link';
@@ -7,6 +9,7 @@ import { useParams } from 'next/navigation';
 import { Suspense, useEffect, useState } from 'react';
 
 function VerifyTokenContent() {
+  const { getCSRFHeaders } = useCSRFContext();
   const params = useParams();
   const token = params?.token as string;
   const [status, setStatus] = useState<'loading' | 'success' | 'error'>('loading');
@@ -23,18 +26,18 @@ function VerifyTokenContent() {
       try {
         const response = await fetch('/api/auth/verify', {
           method: 'POST',
-          headers: { 'Content-Type': 'application/json' },
+          headers: { 'Content-Type': 'application/json', ...getCSRFHeaders() },
           body: JSON.stringify({ token }),
         });
 
-        const data = await response.json();
-
         if (response.ok) {
+          const data = (await response.json()) as { message?: string };
           setStatus('success');
           setMessage(data.message || 'Email verified successfully');
         } else {
+          const { message } = await readApiError(response);
           setStatus('error');
-          setMessage(data.error || 'Verification failed');
+          setMessage(message);
         }
       } catch {
         setStatus('error');
@@ -43,7 +46,7 @@ function VerifyTokenContent() {
     };
 
     verify();
-  }, [token]);
+  }, [token, getCSRFHeaders]);
 
   if (status === 'loading') {
     return (

package/template/src/app/(protected)/settings/billing/page.tsx

@@ -1,5 +1,7 @@
 'use client';
 
+import { useCSRFContext } from '@/lib/csrf-context';
+import { readApiError } from '@/lib/read-api-error';
 import { Suspense, useEffect, useState, useCallback } from 'react';
 import { useSearchParams } from 'next/navigation';
 import { Card, Badge, Button, LinkButton, Spinner } from '@mars-stack/ui';
@@ -132,6 +134,7 @@ function StripeNotConfigured() {
 }
 
 function BillingSettingsContent() {
+  const { getCSRFHeaders } = useCSRFContext();
   const searchParams = useSearchParams();
   const [subscription, setSubscription] = useState<SubscriptionRecord | null>(null);
   const [loading, setLoading] = useState(true);
@@ -182,11 +185,12 @@ function BillingSettingsContent() {
       const response = await fetch('/api/protected/billing/portal', {
         method: 'POST',
         credentials: 'include',
+        headers: { ...getCSRFHeaders() },
       });
 
       if (!response.ok) {
-        const data: { error?: string } = await response.json();
-        throw new Error(data.error ?? 'Failed to create portal session');
+        const { message } = await readApiError(response);
+        throw new Error(message);
       }
 
       const { url } = (await response.json()) as { url: string };

package/template/src/app/(protected)/settings/page.tsx

@@ -2,6 +2,8 @@
 
 import { useState, useEffect, useCallback, type FormEvent } from 'react';
 import { useAuth } from '@/features/auth/context/AuthContext';
+import { useCSRFContext } from '@/lib/csrf-context';
+import { readApiError } from '@/lib/read-api-error';
 import { Card } from '@mars-stack/ui';
 import { FormField, Input, Button, Spinner } from '@mars-stack/ui';
 
@@ -33,6 +35,7 @@ function parseUserAgent(ua: string | null): string {
 }
 
 export default function Settings() {
+  const { getCSRFHeaders } = useCSRFContext();
   const { user, isLoading: authLoading, updateUser } = useAuth();
 
   const [name, setName] = useState('');
@@ -99,18 +102,18 @@ export default function Settings() {
     try {
       const response = await fetch('/api/protected/user/profile', {
         method: 'PATCH',
-        headers: { 'Content-Type': 'application/json' },
+        headers: { 'Content-Type': 'application/json', ...getCSRFHeaders() },
         credentials: 'include',
         body: JSON.stringify({ name: name.trim() }),
       });
 
-      const data = await response.json();
-
       if (!response.ok) {
-        setNameStatus({ type: 'error', message: data.error || 'Failed to update name' });
+        const { message } = await readApiError(response);
+        setNameStatus({ type: 'error', message });
         return;
       }
 
+      const data = (await response.json()) as { user: { name: string } };
       updateUser({ name: data.user.name });
       setNameStatus({ type: 'success', message: 'Display name updated.' });
     } catch {
@@ -127,10 +130,11 @@ export default function Settings() {
       const response = await fetch(`/api/protected/user/sessions/${sessionId}`, {
         method: 'DELETE',
         credentials: 'include',
+        headers: { ...getCSRFHeaders() },
       });
       if (!response.ok) {
-        const data = await response.json();
-        setSessionsStatus({ type: 'error', message: data.error || 'Failed to revoke session.' });
+        const { message } = await readApiError(response);
+        setSessionsStatus({ type: 'error', message });
         return;
       }
       setSessions((prev) => prev.filter((s) => s.id !== sessionId));
@@ -149,10 +153,11 @@ export default function Settings() {
       const response = await fetch('/api/protected/user/sessions', {
         method: 'DELETE',
         credentials: 'include',
+        headers: { ...getCSRFHeaders() },
       });
       if (!response.ok) {
-        const data = await response.json();
-        setSessionsStatus({ type: 'error', message: data.error || 'Failed to revoke sessions.' });
+        const { message } = await readApiError(response);
+        setSessionsStatus({ type: 'error', message });
         return;
       }
       setSessions([]);
@@ -178,15 +183,14 @@ export default function Settings() {
     try {
       const response = await fetch('/api/protected/user/password', {
         method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
+        headers: { 'Content-Type': 'application/json', ...getCSRFHeaders() },
         credentials: 'include',
         body: JSON.stringify({ currentPassword, newPassword }),
       });
 
-      const data = await response.json();
-
       if (!response.ok) {
-        setPasswordStatus({ type: 'error', message: data.error || 'Failed to change password' });
+        const { message } = await readApiError(response);
+        setPasswordStatus({ type: 'error', message });
         return;
       }
 

package/template/src/app/pricing/page.tsx

@@ -5,6 +5,8 @@ import { Card, Badge, Button, LinkButton } from '@mars-stack/ui';
 import { appConfig } from '@/config/app.config';
 import { routes } from '@/config/routes';
 import { useAuth } from '@/features/auth/context/AuthContext';
+import { useCSRFContext } from '@/lib/csrf-context';
+import { readApiError } from '@/lib/read-api-error';
 
 interface PlanTier {
   name: string;
@@ -177,6 +179,7 @@ function PlanCard({
 export default function PricingPage() {
   const [annual, setAnnual] = useState(false);
   const [loadingPriceId, setLoadingPriceId] = useState<string | null>(null);
+  const { getCSRFHeaders } = useCSRFContext();
   const { user } = useAuth();
   const isAuthenticated = !!user;
   const hasStripe = (appConfig.services.payments.provider as string) === 'stripe';
@@ -192,14 +195,14 @@ export default function PricingPage() {
     try {
       const response = await fetch('/api/protected/billing/checkout', {
         method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
+        headers: { 'Content-Type': 'application/json', ...getCSRFHeaders() },
         credentials: 'include',
         body: JSON.stringify({ priceId }),
       });
 
       if (!response.ok) {
-        const data: { error?: string } = await response.json();
-        throw new Error(data.error ?? 'Failed to create checkout session');
+        const { message } = await readApiError(response);
+        throw new Error(message);
       }
 
       const { url } = (await response.json()) as { url: string };

package/template/src/app/providers.tsx

@@ -1,8 +1,13 @@
 'use client';
 
 import { AuthProvider } from '@/features/auth/context/AuthContext';
+import { CSRFProvider } from '@/lib/csrf-context';
 import type { ReactNode } from 'react';
 
 export function Providers({ children }: { children: ReactNode }) {
-  return <AuthProvider>{children}</AuthProvider>;
+  return (
+    <CSRFProvider>
+      <AuthProvider>{children}</AuthProvider>
+    </CSRFProvider>
+  );
 }

package/template/src/features/auth/context/AuthContext.tsx

@@ -1,5 +1,7 @@
 'use client';
 
+import { readApiError } from '@/lib/read-api-error';
+import { useCSRFContext } from '@/lib/csrf-context';
 import { createContext, useContext, useEffect, useState, type ReactNode } from 'react';
 
 export interface User {
@@ -37,6 +39,7 @@ interface AuthProviderProps {
 export function AuthProvider({ children, initialUser = null }: AuthProviderProps) {
   const [user, setUser] = useState<User | null>(initialUser);
   const [isLoading, setIsLoading] = useState(!initialUser);
+  const { getCSRFHeaders } = useCSRFContext();
 
   const refreshAuth = async () => {
     try {
@@ -44,6 +47,8 @@ export function AuthProvider({ children, initialUser = null }: AuthProviderProps
       const response = await fetch('/api/auth/me', { credentials: 'include' });
 
       if (!response.ok) {
+        const { message } = await readApiError(response);
+        console.warn('Session refresh failed:', message);
         setUser(null);
         return;
       }
@@ -64,7 +69,15 @@ export function AuthProvider({ children, initialUser = null }: AuthProviderProps
 
   const logout = async () => {
     try {
-      await fetch('/api/auth/logout', { method: 'POST', credentials: 'include' });
+      const response = await fetch('/api/auth/logout', {
+        method: 'POST',
+        credentials: 'include',
+        headers: { ...getCSRFHeaders() },
+      });
+      if (!response.ok) {
+        const { message } = await readApiError(response);
+        console.warn('Logout response:', message);
+      }
     } catch (error) {
       console.error('Logout error:', error);
     } finally {

package/template/src/features/uploads/components/FileList.tsx

@@ -1,5 +1,7 @@
 'use client';
 
+import { useCSRFContext } from '@/lib/csrf-context';
+import { readApiError } from '@/lib/read-api-error';
 import { useCallback, useEffect, useState } from 'react';
 import { Button, Badge, Spinner } from '@mars-stack/ui';
 import type { FileRecord } from '../types';
@@ -49,6 +51,7 @@ interface FileListProps {
 }
 
 export function FileList({ refreshKey }: FileListProps) {
+  const { getCSRFHeaders } = useCSRFContext();
   const [files, setFiles] = useState<FileRecord[]>([]);
   const [loading, setLoading] = useState(true);
   const [deletingIds, setDeletingIds] = useState<Set<string>>(new Set());
@@ -82,9 +85,12 @@ export function FileList({ refreshKey }: FileListProps) {
       const response = await fetch(`/api/protected/files/${fileId}`, {
         method: 'DELETE',
         credentials: 'include',
+        headers: { ...getCSRFHeaders() },
       });
 
       if (!response.ok) {
+        const { message } = await readApiError(response);
+        console.warn('Delete file failed:', message);
         const restored = files.find((f) => f.id === fileId);
         if (restored) {
           setFiles((prev) => [...prev, restored]);
@@ -102,7 +108,7 @@ export function FileList({ refreshKey }: FileListProps) {
         return next;
       });
     }
-  }, [files]);
+  }, [files, getCSRFHeaders]);
 
   if (loading) {
     return (

package/template/src/lib/csrf-context.tsx

@@ -0,0 +1,21 @@
+'use client';
+
+import { useCSRF } from '@mars-stack/core/auth/hooks';
+import { createContext, useContext, type ReactNode } from 'react';
+
+type CSRFContextValue = ReturnType<typeof useCSRF>;
+
+const CSRFContext = createContext<CSRFContextValue | null>(null);
+
+export function CSRFProvider({ children }: { children: ReactNode }) {
+  const value = useCSRF();
+  return <CSRFContext.Provider value={value}>{children}</CSRFContext.Provider>;
+}
+
+export function useCSRFContext(): CSRFContextValue {
+  const ctx = useContext(CSRFContext);
+  if (!ctx) {
+    throw new Error('useCSRFContext must be used within CSRFProvider');
+  }
+  return ctx;
+}

package/template/src/lib/read-api-error.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from 'vitest';
+import { readApiError } from './read-api-error';
+
+function responseFrom(
+  body: string,
+  init: { status?: number; contentType?: string } = {},
+): Response {
+  const { status = 400, contentType = 'text/plain; charset=utf-8' } = init;
+  return new Response(body, {
+    status,
+    headers: { 'Content-Type': contentType },
+  });
+}
+
+describe('readApiError', () => {
+  it('returns JSON error and optional code', async () => {
+    const res = responseFrom(JSON.stringify({ error: 'Bad input', code: 'VALIDATION' }), {
+      contentType: 'application/json',
+    });
+    const out = await readApiError(res);
+    expect(out.message).toBe('Bad input');
+    expect(out.code).toBe('VALIDATION');
+  });
+
+  it('does not throw on 403 plain-text CSRF body', async () => {
+    const res = responseFrom('CSRF token validation failed', {
+      status: 403,
+      contentType: 'text/plain; charset=utf-8',
+    });
+    const out = await readApiError(res);
+    expect(out.message).toBe('CSRF token validation failed');
+  });
+
+  it('uses fallback when body is empty and status is 403', async () => {
+    const res = responseFrom('', { status: 403 });
+    const out = await readApiError(res);
+    expect(out.message).toContain('refreshing');
+  });
+
+  it('returns plain text when JSON Content-Type but body is not valid JSON', async () => {
+    const res = responseFrom('not json', { contentType: 'application/json' });
+    const out = await readApiError(res);
+    expect(out.message).toBe('not json');
+  });
+
+  it('prefers message field when error is absent', async () => {
+    const res = responseFrom(JSON.stringify({ message: 'Rate limited' }), {
+      contentType: 'application/json',
+    });
+    const out = await readApiError(res);
+    expect(out.message).toBe('Rate limited');
+  });
+});

package/template/src/lib/read-api-error.ts

@@ -0,0 +1,59 @@
+/**
+ * Safe parsing for API error responses. Proxies may return **403** with a **plain-text** body;
+ * calling `response.json()` on that body throws `SyntaxError` and masks the real failure.
+ *
+ * @see template/src/proxy.ts — CSRF exemptions must stay aligned with client calls.
+ */
+
+export interface ReadApiErrorResult {
+  /** User-visible or developer-actionable message */
+  message: string;
+  /** Optional machine-readable code when the server returned JSON with `code` */
+  code?: string;
+}
+
+function pickString(value: unknown): string | undefined {
+  if (typeof value === 'string' && value.trim()) return value.trim();
+  return undefined;
+}
+
+function fallbackMessage(status: number): string {
+  if (status === 403) {
+    return 'Request blocked. Try refreshing the page, then sign in again if the problem continues.';
+  }
+  if (status === 401) {
+    return 'Sign in required or session expired.';
+  }
+  return `Request failed (${status}).`;
+}
+
+/**
+ * Reads a failed `Response` and returns a safe message without throwing on non-JSON bodies.
+ * Consumes the response body (do not call `response.json()` afterward).
+ */
+export async function readApiError(response: Response): Promise<ReadApiErrorResult> {
+  const contentType = response.headers.get('content-type') ?? '';
+  const raw = await response.text();
+  const trimmed = raw.trim();
+
+  if (!trimmed) {
+    return { message: fallbackMessage(response.status) };
+  }
+
+  if (contentType.includes('application/json')) {
+    try {
+      const parsed: unknown = JSON.parse(trimmed);
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        const obj = parsed as Record<string, unknown>;
+        const message =
+          pickString(obj.error) ?? pickString(obj.message) ?? pickString(obj.title) ?? trimmed;
+        const code = pickString(obj.code);
+        return code ? { message, code } : { message };
+      }
+    } catch {
+      // Malformed JSON — fall through to plain text
+    }
+  }
+
+  return { message: trimmed };
+}

package/template/src/proxy.ts

@@ -3,6 +3,7 @@ import { createCSRFProtection } from '@mars-stack/core/auth/csrf';
 import { routes } from '@/config/routes';
 import { NextRequest, NextResponse } from 'next/server';
 
+/** CSRF validation is skipped for these path prefixes — keep aligned with `scripts/check-csrf-client-fetch.mjs` and client `fetch` calls. */
 const csrfExemptRoutes = ['/api/csrf', '/api/webhooks', '/api/auth/verify', '/api/auth/reset'];
 
 const csrf = createCSRFProtection({