Cross-Subdomain Authentication Guide#

This document explains the architecture and implementation details for implementing secure, performant authentication across multiple subdomain projects using edge middleware and client-side data fetching.

Table of Contents#

1. Architecture Overview
2. Security Model
3. Cookie Mechanics
4. Edge Middleware Pattern
5. Client-Side Data Fetching
6. SWR Implementation Deep Dive
7. CORS Configuration
8. Complete Implementation
9. Performance Characteristics
10. Security Analysis

Architecture Overview#

The Pattern#

Key Benefits#

• Fast: Edge middleware (~5ms) + static pages (CDN) + client hydration
• Cheap: No SSR costs, minimal edge function costs
• Secure: HttpOnly cookies + JWT validation + edge blocking
• Simple: Centralized auth logic, minimal per-project code
• Scalable: Static generation, CDN delivery

Security Model#

Defense in Depth#

Cookie Mechanics#

Cookie Configuration#

When the auth service sets the JWT cookie:

Browser Behavior#

Cookie IS automatically sent to:

• ✅ auth.gaz.codes/api/profile
• ✅ project-a.gaz.codes/api/anything
• ✅ project-b.gaz.codes/api/anything
• ✅ Any subdomain of .gaz.codes

Cookie is NOT sent to:

• ❌ otherdomain.com
• ❌ gaz.codes.evil.com (not a subdomain)
• ❌ HTTP sites (when Secure flag is set)

JavaScript CANNOT:

• ❌ Read: document.cookie won't show HttpOnly cookies
• ❌ Write: Cannot modify or delete HttpOnly cookies
• ❌ Send to wrong domain: Browser enforces domain restriction

JavaScript CAN:

• ✅ Trigger fetch requests that include the cookie (with credentials: 'include')
• ✅ Receive data from API that validated the cookie

Client-Side Fetch Behavior#

What happens:

1. Browser checks: Is auth.gaz.codes same-site as project-a.gaz.codes? ✓
2. Browser checks: Does cookie domain .gaz.codes match? ✓
3. Browser checks: Is connection HTTPS (Secure flag)? ✓
4. Browser checks: Is SameSite policy satisfied? ✓
5. Browser automatically attaches cookie to request
6. JavaScript never sees the cookie value
7. JavaScript receives the response data

Edge Middleware Pattern#

Shared Middleware Utility#

Create a reusable middleware factory in your shared packages:

Per-Project Implementation#

Each project uses the shared middleware with minimal configuration:

That's it! ~10 lines per project.

Latency Characteristics#

Client-Side Data Fetching#

Basic Pattern#

Timeline#

Basic Hook Implementation#

SWR Implementation Deep Dive#

Why SWR?#

SWR (stale-while-revalidate) is a React hooks library for data fetching that provides:

1. Automatic caching: Fetch once, use everywhere
2. Deduplication: Multiple components requesting same data = single network request
3. Focus revalidation: Refresh data when user returns to tab
4. Automatic retries: Network failures are retried automatically
5. Optimistic updates: Update UI before server confirms
6. Pagination support: Built-in infinite loading
7. TypeScript support: Full type safety

Installation#

Basic SWR Implementation#

SWR Magic: Automatic Deduplication#

How it works:

1. Component A calls useAuth() → SWR makes network request
2. Component B calls useAuth() → SWR returns cached data (no network request)
3. Component C calls useAuth() → SWR returns cached data (no network request)
4. When data updates, ALL components re-render automatically

Advanced SWR Configuration#

SWR Configuration Explained#

Deduplication#

• If useAuth() is called multiple times within 60s, only the first call makes a network request
• Subsequent calls return cached data immediately
• After 60s, the next call will make a fresh request

Revalidation Strategies#

User switches back to your tab → SWR automatically refreshes data to ensure it's current.

Network drops then reconnects → SWR refreshes data automatically.

If cached data is older than dedupingInterval → SWR fetches fresh data in background.

Retry Logic#

Behavior:

Useful for handling temporary network issues or server downtime.

Optimistic Updates#

SWR with Multiple Endpoints#

Global SWR Configuration#

SWR with TypeScript#

SWR Performance Comparison#

SWR Debugging#

CORS Configuration#

Your auth API must allow cross-subdomain requests:

Why each header:

Complete Implementation#

Step 1: Install Dependencies#

Step 2: Create Shared JWT Utilities#

Step 3: Create Shared Auth Middleware#

Step 4: Create Shared Auth Hook with SWR#

Step 5: Implement in Projects#

Step 6: Configure CORS in Auth API#

Performance Characteristics#

Latency Breakdown#

Total time to interactive: ~250ms

Compare to SSR approach:

SSR time to interactive: ~400ms (60% slower)

Cost Analysis (Vercel Pro)#

Edge Middleware:

SSR:

Savings: ~94% cheaper with edge + static

Caching Benefits (with SWR)#

Security Analysis#

Attack Vectors & Mitigations#

1. XSS (Cross-Site Scripting)#

Attack: Inject JavaScript to steal auth token

Mitigation: HttpOnly cookie

2. CSRF (Cross-Site Request Forgery)#

Attack: Malicious site triggers authenticated request

Mitigation: SameSite=Lax cookie

3. Token Theft via MitM (Man-in-the-Middle)#

Attack: Intercept network traffic to steal token

Mitigation: Secure flag

4. Subdomain Takeover#

Attack: Attacker gains control of subdomain (e.g., old.gaz.codes), steals cookies

Mitigation: Monitor DNS, decommission unused subdomains

5. JWT Signature Forgery#

Attack: Craft fake JWT to impersonate user

Mitigation: Strong secret + verification

6. Replay Attacks#

Attack: Steal valid JWT, reuse to access account

Mitigation: Short expiry + refresh tokens

Security Checklist#

• ✅ Cookie has HttpOnly flag
• ✅ Cookie has Secure flag
• ✅ Cookie has SameSite=Lax or Strict
• ✅ Cookie domain is .gaz.codes (not broader)
• ✅ JWT secret is 256+ bits, securely stored
• ✅ JWT signature verified on every request
• ✅ Access tokens expire within 1 hour
• ✅ HTTPS enforced across all subdomains
• ✅ CORS properly configured (specific origins only)
• ✅ Unused subdomains decommissioned
• ✅ Regular security audits

Troubleshooting#

Cookie Not Being Sent#

Symptom: Client-side fetch returns 401, even though user is logged in

Causes:

1. Missing credentials: 'include' in fetch
2. CORS not configured properly
3. Cookie domain mismatch

Debug:

Fix:

CORS Preflight Failures#

Symptom: OPTIONS request returns error, GET/POST never fires

Debug:

Expected response:

Middleware Redirect Loop#

Symptom: Endless redirects between project and auth

Cause: Middleware misconfigured, redirects authenticated users

Debug:

SWR Not Caching#

Symptom: Every component mount triggers new network request

Cause: SWR key is not stable (changes on every render)

Debug:

Additional Resources#

• SWR Documentation
• Next.js Middleware
• JWT Best Practices
• OWASP Cookie Security
• MDN: HTTP Cookies

Summary#

This architecture provides:

✅ Security: HttpOnly cookies, JWT validation, edge blocking ✅ Performance: Edge middleware (~5ms), static pages, SWR caching ✅ Cost: ~94% cheaper than SSR ✅ Developer Experience: Simple hook API, automatic caching, type safety ✅ Scalability: Static generation, CDN delivery, minimal server load

The combination of edge middleware for authentication gates and SWR for client-side data fetching provides the optimal balance of security, performance, and developer experience for cross-subdomain authentication.