protect-spa-and-api

name	protect-spa-and-api
description	Protect a React/Next.js SPA with route guards and middleware, and protect an API with token-verification middleware (signature + iss + aud + exp). Covers CORS configuration and CSRF defense. Applies to both the web-app and the API/backend targets.

Skill: protect-spa-and-api

Invoked by: any agent implementing route protection for a Next.js app or API token verification; ravenclaude-core/security-reviewer for any auth middleware change.

When to invoke: adding protected routes to a Next.js app; implementing API token verification; hardening an existing app against CORS or CSRF vulnerabilities; onboarding a new service to require authentication.

Output: Next.js middleware route guard + API token-verification middleware + CORS config + CSRF defense + verification checklist.

---

Boundary

This skill protects routes and APIs using the authenticated identity established by google-sso-setup and session-and-token-management. Authorization (which authenticated user can access which resource) is handled by the authorization-rbac skill and, for data rows, by the data-platform plugin's rls-policy-authoring skill. Security-sensitive code routes to ravenclaude-core/security-reviewer before production deploy.

---

Protecting the Next.js web app

Approach A — Next.js Middleware (recommended for App Router)

middleware.ts at the project root runs on every matched request, before rendering. The best place to enforce authentication globally.

// middleware.ts — conceptual; security-review before production
import { createServerClient } from "@supabase/ssr";
import { NextResponse } from "next/server";
import type { NextRequest } from "next/server";

// Routes that don't require authentication
const PUBLIC_PATHS = ["/", "/login", "/auth/callback", "/auth/error"];

export async function middleware(request: NextRequest) {
  let response = NextResponse.next({ request: { headers: request.headers } });

  const supabase = createServerClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
    {
      cookies: {
        getAll: () => request.cookies.getAll(),
        setAll: (cs) => {
          cs.forEach(({ name, value }) => request.cookies.set(name, value));
          response = NextResponse.next({ request: { headers: request.headers } });
          cs.forEach(({ name, value, options }) =>
            response.cookies.set(name, value, options),
          );
        },
      },
    },
  );

  // getUser() validates the session token server-side — do not use getSession() here
  // getSession() trusts the cookie without server-side validation
  const { data: { user } } = await supabase.auth.getUser();

  const path = request.nextUrl.pathname;
  const isPublic = PUBLIC_PATHS.some((p) => path === p || path.startsWith(p + "/"));

  if (!user && !isPublic) {
    const redirectUrl = request.nextUrl.clone();
    redirectUrl.pathname = "/login";
    redirectUrl.searchParams.set("next", path);
    return NextResponse.redirect(redirectUrl);
  }

  return response;
}

export const config = {
  matcher: [
    // Run on all paths except static files and _next internals
    "/((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)",
  ],
};

Important: use supabase.auth.getUser() (makes a network call to validate the JWT server-side), not supabase.auth.getSession() (trusts the cookie without validation). [unverified — confirm this distinction in current Supabase Auth docs]

Approach B — Server Component redirect

For per-page protection in App Router Server Components:

// app/dashboard/page.tsx
import { redirect } from "next/navigation";
import { createServerClient } from "@supabase/ssr";
import { cookies } from "next/headers";

export default async function DashboardPage() {
  const cookieStore = cookies();
  const supabase = createServerClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
    { cookies: { getAll: () => cookieStore.getAll(), setAll: () => {} } },
  );

  const { data: { user } } = await supabase.auth.getUser();
  if (!user) redirect("/login?next=/dashboard");

  return <div>Dashboard for {user.email}</div>;
}

Use Middleware (Approach A) for broad protection + Server Component checks for fine-grained page-level control.

---

Protecting the API

Every protected API route must verify the caller's identity server-side. Never trust client-supplied identity claims without verification.

Supabase-backed API routes

// app/api/data/route.ts — protected API route
import { createServerClient } from "@supabase/ssr";
import { cookies } from "next/headers";
import { NextResponse } from "next/server";

export async function GET(request: Request) {
  const cookieStore = cookies();
  const supabase = createServerClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
    { cookies: { getAll: () => cookieStore.getAll(), setAll: () => {} } },
  );

  const { data: { user }, error } = await supabase.auth.getUser();
  if (!user || error) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }

  // user.id is auth.uid() — data scoping is handled by Supabase RLS automatically
  // when using the anon client with the user's session cookie
  const { data } = await supabase.().();
   .(data);
}

External / standalone API (Bearer token)

For APIs not behind Supabase's client, verify the JWT from the Authorization: Bearer <token> header:

// lib/auth/verify-token.ts — conceptual; security-review before production
// Uses 'jose' library for JWKS-based verification
// npm install jose
import { createRemoteJWKSet, jwtVerify } from "jose";

// Google's JWKS endpoint [unverified — confirm current URL]
const GOOGLE_JWKS = createRemoteJWKSet(
  new URL("https://www.googleapis.com/oauth2/v3/certs"),
);

export async function verifyGoogleIdToken(token: string) {
  const { payload } = await jwtVerify(token, GOOGLE_JWKS, {
    issuer: "https://accounts.google.com",         // or accounts.google.com
    audience: process.env.GOOGLE_CLIENT_ID!,        // your OAuth client ID
    // algorithms: ['RS256'] — jose infers from JWKS
  });

  // payload.sub, payload.email, payload.exp already validated
  return payload;
}

// In your API handler:
export async function GET(request: Request) {
  const authHeader = request.headers.get("Authorization");
   (!authHeader?.()) {
      (, { :  });
  }

   token = authHeader.();
   {
     claims =  (token);
    
  }  {
      (, { :  });
  }
}

Checklist for token verification:

• Signature verified against JWKS (not hardcoded public key)
• iss matches expected issuer
• aud matches your application's client ID
• exp checked (library handles automatically if configured)
• Algorithm explicitly pinned (do not accept alg: none)
• Security review completed before production

---

CORS configuration

CORS controls which origins can make cross-origin requests to your API.

// next.config.ts — CORS headers for API routes
const nextConfig = {
  async headers() {
    return [
      {
        source: "/api/:path*",
        headers: [
          // Allow only your own app's origin and any known dashboard embed origins
          { key: "Access-Control-Allow-Origin", value: "https://app.example.com" },
          { key: "Access-Control-Allow-Methods", value: "GET, POST, PUT, DELETE, OPTIONS" },
          { key: "Access-Control-Allow-Headers", value: "Content-Type, Authorization" },
          { key: "Access-Control-Allow-Credentials", value: "true" },
        ],
      },
    ];
  },
};

CORS rules:

• Do not use Access-Control-Allow-Origin: * for authenticated APIs.
• Specify an explicit allowlist of origins.
• Access-Control-Allow-Credentials: true requires a non-wildcard origin.
• CORS is not a security boundary for server-to-server calls (it only applies in browsers).

---

CSRF defense

Cookies are sent automatically by the browser on cross-site requests. Mitigations:

1. SameSite=Lax or Strict cookie flag — primary defense; see session-and-token-management skill.
2. CSRF token for state-mutating routes — double-submit cookie or synchronizer token pattern for POST/PUT/DELETE routes that cannot rely on SameSite=Strict alone.
3. Content-Type: application/json check — simple APIs can reject requests that don't send the correct Content-Type header (pre-flight required for non-simple CORS requests).
4. Origin/Referer header validation — secondary check; referer can be stripped by privacy settings.

Supabase API routes benefit from the built-in cookie SameSite protection when using @supabase/ssr. [unverified — confirm in current Supabase SSR docs]

---

Anti-patterns this skill flags

• Using supabase.auth.getSession() in middleware instead of getUser() — getSession trusts the unverified cookie
• Returning sensitive data from an API route without verifying the session first
• Access-Control-Allow-Origin: * on authenticated API routes
• No SameSite flag on auth cookies — CSRF-vulnerable
• Skipping iss or aud validation in manual token verification — replay across issuers/apps
• Accepting alg: none in JWT verification — allows unsigned tokens
• Protecting only page routes but not API routes (API must enforce auth independently)
• Redirect-after-auth using an unvalidated next query parameter — open redirect vulnerability; validate next is a relative path on your own domain

---

Verification checklist

• All protected routes redirect to login when session is absent
• Middleware uses getUser() not getSession() for validation
• API routes return 401 when session/token is absent or invalid
• Token verification checks signature + iss + aud + exp
• CORS headers explicitly list allowed origins (no wildcard)
• Auth cookies have HttpOnly, Secure, SameSite flags
• next redirect parameter validated as relative path
• Security review completed before production deploy

---

See also

• Skill: ../session-and-token-management/SKILL.md — the session that this skill reads to protect routes
• Skill: ../authorization-rbac/SKILL.md — what to do once identity is verified (role checks)
• Skill: ../gate-the-dashboard/SKILL.md — protecting the analytics dashboard specifically
• Best-practice: ../../best-practices/validate-id-tokens-server-side.md
• data-platform: ../../../data-platform/skills/rls-policy-authoring/SKILL.md — data-row authorization that follows identity verification
• Security escalation: ../../../ravenclaude-core/agents/security-reviewer.md