@mars-stack/cli 7.0.4 → 7.0.5

package/package.json

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

package/template/AGENTS.md

@@ -64,6 +64,7 @@ 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
 
@@ -79,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

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/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({