@zigrivers/scaffold 3.6.0 → 3.8.0

package/content/knowledge/web-app/web-app-rendering-strategies.md

@@ -0,0 +1,133 @@
+---
+name: web-app-rendering-strategies
+description: SSR TTFB and SEO benefits, SSG for content sites, ISR, streaming SSR, React Server Components, and progressive hydration patterns
+topics: [web-app, rendering, ssr, ssg, isr, streaming, react-server-components, hydration]
+---
+
+Rendering strategy is the foundational technical decision in a web app — it determines server infrastructure requirements, SEO characteristics, performance profile, and the developer model for data fetching. Understanding the precise mechanics of each strategy (not just their marketing descriptions) is essential for making and defending the right choice for a given project.
+
+## Summary
+
+Rendering strategy determines server infrastructure, SEO characteristics, and performance profile. SSR provides SEO and fast LCP but adds server cost and TTFB. SSG gives sub-100ms TTFB from CDN but data is stale until rebuild. ISR extends SSG with per-route revalidation. Streaming SSR and React Server Components reduce bundle size and improve perceived performance by streaming content progressively. Most real-world apps need a hybrid approach.
+
+## Deep Guidance
+
+### SSR: Benefits and Real Costs
+
+Server-Side Rendering generates HTML on the server for each request. The benefits are real but often overstated:
+
+**Benefits:**
+- **SEO**: Search engines receive pre-rendered HTML immediately. Critical for pages that must be indexed.
+- **LCP on slow connections**: User sees content before JavaScript downloads and executes. Significant for mobile users on 3G.
+- **Social sharing**: OG tags, Twitter Cards, and link previews work because the HTML is complete on the server response.
+- **Auth-gated content**: Server can read session cookies and render personalized HTML without a client-side auth check causing layout flash.
+
+**Real costs (often understated):**
+- **TTFB**: Server must complete data fetching before sending the first byte. A slow database query delays the entire page. CSR serves a shell HTML in ~50 ms (CDN); SSR may take 200–500 ms for a database-backed page.
+- **Server load**: Every page view consumes server CPU. At scale, this is a significant infrastructure cost vs. CDN-served static pages.
+- **Caching complexity**: SSR responses may be personalized and cannot be cached at the CDN without careful `Vary` headers and cache key design.
+- **Cold starts**: In serverless environments, SSR functions have cold start latency that static serving does not.
+
+### SSG: When It Is the Right Tool
+
+Static Site Generation pre-builds every page at deploy time. It is the correct choice for:
+
+- Content that changes at most a few times per day (blog, docs, marketing pages)
+- Pages with no user-specific personalization in the HTML
+- Maximum performance requirements (sub-100 ms TTFB from CDN)
+
+SSG limitations are real and must be understood:
+- **Build time**: Every page generates during CI. At 10,000 pages with 100 ms per page: 17 minutes of build time. Use incremental builds and build caching to mitigate.
+- **Data freshness**: Pages are stale from the moment they are built. A product price change requires a rebuild to appear. Use on-demand revalidation (ISR) for this case.
+
+### ISR: Incremental Static Regeneration
+
+ISR extends SSG with per-route revalidation intervals. A page marked `revalidate: 60` is served from the CDN static cache, but regenerated in the background every 60 seconds when a visitor triggers it:
+
+- Stale-while-revalidate semantics: the first visitor after 60 seconds gets the old page; the next visitor gets the fresh page
+- The regeneration happens server-side, not in response to a specific user — it is eventual consistency, not real-time
+- On-demand ISR (via `res.revalidate(path)`) allows webhook-triggered immediate rebuilds — product price change → webhook → rebuild that product page within seconds
+
+ISR is appropriate when "a few seconds to a minute stale" is acceptable and you want CDN-level performance without a full rebuild per data change.
+
+### Streaming SSR
+
+React 18 and Next.js App Router support streaming HTML responses using `renderToPipeableStream` and `<Suspense>`:
+
+1. Server sends the page shell (header, navigation, above-fold layout) immediately — TTFB is fast
+2. Data-dependent sections are wrapped in `<Suspense>` with a fallback (skeleton)
+3. As each suspended section's data resolves, React streams its HTML directly into the response
+4. Browser progressively renders content as it arrives
+
+This transforms LCP dramatically: users see layout and fast content immediately; slow data sections (product reviews, recommendations) arrive asynchronously without blocking the critical paint.
+
+**Implementation pattern:**
+```tsx
+// app/product/[id]/page.tsx
+export default function ProductPage({ params }) {
+  return (
+    <main>
+      <ProductHero id={params.id} />        {/* Fast: renders immediately */}
+      <Suspense fallback={<ReviewSkeleton />}>
+        <ProductReviews id={params.id} />   {/* Slow: streams in when ready */}
+      </Suspense>
+      <Suspense fallback={<RecommendationSkeleton />}>
+        <Recommendations id={params.id} />  {/* Slow: streams in when ready */}
+      </Suspense>
+    </main>
+  );
+}
+```
+
+### React Server Components
+
+RSC is a model where components run exclusively on the server and send a serialized component description to the client — not HTML, not JavaScript:
+
+- **Server Components**: Zero client-side JS. Read databases, file systems, environment variables directly. Not interactive.
+- **Client Components**: Marked with `"use client"`. Run on both server (for initial HTML) and client (for interactivity). Receive server component output as props.
+- **Benefit**: A product page with 40 KB of component code can ship 5 KB to the browser if most components are server-only.
+
+The mental model shift: the client-server boundary is now drawn at the component level, not the page level. This is the most significant change in React architecture since hooks.
+
+### Choosing a Strategy: Decision Framework
+
+Answer these questions in order:
+
+1. **Does this page need SEO?** If no → CSR. If yes → continue.
+2. **Is the content personalized per user?** If no → SSG or ISR. If yes → SSR or RSC.
+3. **How stale can the data be?** Minutes acceptable → ISR. Real-time required → SSR.
+4. **How much traffic?** Millions of pageviews/day → CDN-served (SSG/ISR) wins on cost. Low traffic → SSR is fine.
+
+Most real-world apps need a hybrid: SSG for marketing, ISR for product listings, SSR for checkout, CSR for the user dashboard.
+
+### Progressive Hydration Pattern
+
+In Next.js without RSC, implement progressive hydration by deferring non-critical component hydration:
+
+```typescript
+import dynamic from "next/dynamic";
+
+// Defer hydration until the component is in the viewport
+const HeavyWidget = dynamic(() => import("./HeavyWidget"), {
+  ssr: false,  // Not needed for SEO
+  loading: () => <WidgetSkeleton />,
+});
+
+// Or: load but don't hydrate until user interacts
+const ChatWidget = dynamic(() => import("./ChatWidget"), {
+  ssr: false,
+});
+```
+
+Each dynamically imported component creates a separate JS chunk. Only load what is needed for the current page — analyze your bundle with `@next/bundle-analyzer` or `rollup-plugin-visualizer`.
+
+### Hydration Mismatch Debugging
+
+The most common SSR debugging problem is hydration mismatches — the server renders different HTML than the client expects. Common causes:
+
+- Browser-only APIs (`window`, `document`, `navigator`) accessed during server render
+- Date formatting that differs between server timezone and client timezone
+- Random values (`Math.random()`, `uuid()`) that differ between server and client renders
+- Conditional rendering based on browser features (`typeof window !== 'undefined'`)
+
+Fix by moving browser-only code into `useEffect` (runs only on client) or by using `dynamic(() => import(...), { ssr: false })` for components that inherently require the browser. Never suppress hydration warnings with `suppressHydrationWarning` except for timestamps and user-agent-dependent content where mismatch is expected and benign.

package/content/knowledge/web-app/web-app-requirements.md

@@ -0,0 +1,112 @@
+---
+name: web-app-requirements
+description: SSR/SPA decision criteria, Core Web Vitals budgets, responsive breakpoints, browser support matrix, PWA considerations, and SEO requirements
+topics: [web-app, requirements, performance, pwa, seo, accessibility]
+---
+
+Defining web app requirements before writing a line of code prevents the most expensive rework in the project lifecycle. Rendering strategy, performance budgets, and browser support targets affect every architectural decision downstream. Locking these down early — with explicit tradeoff acknowledgment — removes ambiguity and gives the team a shared definition of "done."
+
+## Summary
+
+Web app requirements establish rendering strategy (SSR for SEO, SPA for authenticated apps, hybrid for content-heavy sites), Core Web Vitals budgets (LCP < 2.5s, INP < 200ms, CLS < 0.1), responsive breakpoints from a shared token set, browser support matrix encoded via Browserslist, PWA scope decisions, and SEO requirements. Lock these down before sprint one.
+
+## Deep Guidance
+
+### SSR vs SPA Decision Criteria
+
+Rendering strategy is the first architectural decision. The wrong choice costs weeks of retrofit:
+
+- **Choose SSR (Next.js, Remix, SvelteKit, Nuxt)** when: SEO is critical (content sites, e-commerce, marketing), first-paint performance matters on slow connections, users are on low-powered devices, or content changes frequently and needs crawlability.
+- **Choose SPA (React, Vue, Angular with CSR)** when: the app is behind authentication (no SEO need), interactions are highly dynamic (dashboards, tools, editors), and the user base is on capable hardware with fast connections.
+- **Choose hybrid (SSG + client hydration)** when: most pages are static but some routes need real-time data. This is the default for most content-heavy sites — build pages at deploy time, hydrate interactive islands on the client.
+
+Never choose SSR just because it is the current trend. Server rendering adds operational complexity (cold starts, caching headers, streaming), infrastructure cost, and harder debugging. Quantify the SEO and performance benefit before committing.
+
+### Core Web Vitals Budgets
+
+Establish explicit targets before sprint one. These directly affect Google ranking and user conversion:
+
+- **LCP (Largest Contentful Paint)**: Target under 2.5 seconds on a 3G mobile connection. Optimize with image preloads, font subsetting, and eliminating render-blocking resources.
+- **FID / INP (Interaction to Next Paint)**: Target under 200 ms. Long JavaScript tasks block the main thread. Break up tasks, defer non-critical code, use Web Workers for heavy computation.
+- **CLS (Cumulative Layout Shift)**: Target under 0.1. Reserve space for images and embeds. Avoid inserting content above the fold after initial paint.
+
+Set budget alerts in Lighthouse CI on every PR. Treat regressions as build failures.
+
+### Responsive Breakpoints
+
+Establish a breakpoint set and document it in the design system. A common mobile-first set:
+
+- **Mobile**: base styles (320–767 px)
+- **Tablet**: 768 px and up
+- **Desktop**: 1024 px and up
+- **Wide**: 1280 px and up (optional; cap content width at 1440 px to prevent excessive line length)
+
+Do not invent per-component breakpoints. All breakpoints must come from a shared token set in CSS custom properties or a design token file.
+
+### Browser Support Matrix
+
+Define this explicitly and commit it to the repo's `CONTRIBUTING.md` or a `BROWSERS.md` file:
+
+- **Evergreen tier** (full support): Chrome, Edge, Firefox, Safari — last 2 major versions
+- **Legacy tier** (functional, degraded): IE 11, Safari 12 — no graceful degradation unless business requires it
+- **Mobile browsers**: Chrome for Android, Safari iOS — test on real devices, not just emulators
+
+Use Browserslist to encode the matrix and share it across tools (Babel, PostCSS Autoprefixer, ESLint). Target: `"> 0.5%, last 2 versions, not dead"` as a safe default.
+
+### PWA Considerations
+
+Decide at project start whether PWA features are required:
+
+- **Service worker / offline**: Required if the app must function without connectivity or if mobile install is a goal. Adds complexity — cache invalidation is the #1 source of PWA bugs.
+- **Web App Manifest**: Low cost, high value. Enables mobile home screen install and controls display mode. Add for any app targeting mobile users.
+- **Push notifications**: Requires backend infrastructure and user permission flows. Scope carefully — most apps do not need this.
+
+### SEO Requirements
+
+For public-facing apps:
+
+- Server-render or statically generate all pages indexed by search engines. Client-rendered content is not reliably indexed.
+- Implement `<title>`, `<meta description>`, Open Graph, and structured data (JSON-LD) on every route.
+- Generate a sitemap at deploy time; submit to Google Search Console.
+- Ensure canonical URLs, `robots.txt`, and proper handling of 404/301/302 responses.
+
+### Performance Budget Enforcement
+
+Encode budgets in `budget.json` and enforce in CI:
+
+```json
+{
+  "resourceSizes": [
+    { "resourceType": "script", "budget": 300 },
+    { "resourceType": "total", "budget": 1000 },
+    { "resourceType": "image", "budget": 500 }
+  ],
+  "timings": [
+    { "metric": "first-contentful-paint", "budget": 1500 },
+    { "metric": "interactive", "budget": 3500 },
+    { "metric": "largest-contentful-paint", "budget": 2500 }
+  ]
+}
+```
+
+Run `lighthouse-ci` on every PR against a representative page. Block merges that regress LCP, INP, or CLS beyond tolerance.
+
+### Defining "Supported" vs "Functional"
+
+Do not conflate browser support tiers. Define what each means:
+
+- **Supported**: All features work, tested in CI, regressions are P0 bugs.
+- **Functional**: Core user journey works, advanced features may degrade gracefully.
+- **Unsupported**: App may not load at all; display an upgrade notice.
+
+Document which tier each browser falls into and socialize it with stakeholders before launch. Retrofitting support after launch is significantly more expensive than scoping it at project start.
+
+### Accessibility Requirements
+
+Accessibility is a requirement, not a feature. Decide on the compliance target upfront:
+
+- **WCAG 2.1 AA**: Industry baseline. Required for most government and enterprise customers.
+- **WCAG 2.2 AA**: Current standard; prefer this for new projects.
+- **Section 508**: Required for US federal contractors.
+
+Automated tools (axe, Lighthouse) catch ~30–40% of issues. Manual keyboard navigation and screen reader testing (VoiceOver, NVDA) must supplement automation.

package/content/knowledge/web-app/web-app-security.md

@@ -0,0 +1,193 @@
+---
+name: web-app-security
+description: XSS prevention, Content Security Policy, CSRF tokens, clickjacking, Subresource Integrity, dependency auditing, and OWASP top 10 for web apps
+topics: [web-app, security, xss, csp, csrf, clickjacking, owasp, dependency-auditing]
+---
+
+Web application security failures are among the most costly and common causes of data breaches. The OWASP Top 10 has catalogued the same categories of vulnerabilities for decades — not because they are new, but because they recur in every generation of frameworks and technologies. Understanding the attack vectors and their mitigations is not optional for engineers building user-facing web applications. Security must be designed in, not bolted on.
+
+## Summary
+
+### XSS (Cross-Site Scripting) Prevention
+
+XSS occurs when attacker-controlled content is rendered as executable script in a victim's browser. It is the most prevalent web vulnerability class.
+
+**Three XSS types:**
+- **Stored XSS** — malicious script is stored in the database and rendered for all users (e.g., a comment containing `<script>`)
+- **Reflected XSS** — malicious script is in the URL and reflected back in the response (e.g., a search page rendering the query parameter unsanitized)
+- **DOM-based XSS** — malicious script is injected via client-side JavaScript manipulation of the DOM (e.g., `element.innerHTML = location.hash`)
+
+**Primary defense: output encoding.** Modern React, Vue, and Angular frameworks automatically escape string interpolation. The vulnerabilities arise when developers bypass the framework: `dangerouslySetInnerHTML`, `v-html`, `innerHTML`, `document.write`, `eval()`.
+
+**Content Security Policy (CSP):** A `Content-Security-Policy` response header instructs the browser to only execute scripts from trusted sources:
+
+```
+Content-Security-Policy:
+  default-src 'self';
+  script-src 'self' https://trusted-cdn.com;
+  style-src 'self' 'unsafe-inline';
+  img-src 'self' data: https:;
+  font-src 'self' https://fonts.gstatic.com;
+  connect-src 'self' https://api.example.com;
+  frame-ancestors 'none';
+  upgrade-insecure-requests;
+```
+
+`'unsafe-inline'` in `script-src` defeats the XSS protection benefit. Use nonces (`'nonce-{random}'`) or hashes instead for inline scripts.
+
+### Clickjacking Prevention
+
+Clickjacking loads your application in a hidden `<iframe>` on an attacker's page. Users believe they are clicking on the attacker's UI but are actually clicking your application's buttons.
+
+**Defense:** `Content-Security-Policy: frame-ancestors 'none'` (preferred) or the older `X-Frame-Options: DENY`. `frame-ancestors 'none'` prevents your app from being embedded in any frame. Use `frame-ancestors 'self'` if you need to allow same-origin framing.
+
+### CSRF Protection
+
+Cross-Site Request Forgery tricks an authenticated user into submitting a request to your application from an attacker's site. The browser automatically sends cookies, making the forged request appear legitimate.
+
+**Primary defense:** `SameSite=Strict` or `SameSite=Lax` cookies. With `SameSite=Strict`, the cookie is never sent on cross-site requests, making CSRF impossible.
+
+**Secondary defense for legacy or cross-site scenarios:** Synchronizer token pattern — include a CSRF token in every form/request and validate it on the server.
+
+### Subresource Integrity (SRI)
+
+When loading scripts or stylesheets from CDNs, SRI prevents a compromised CDN from serving malicious content:
+
+```html
+<script
+  src="https://cdn.example.com/library.min.js"
+  integrity="sha384-oqVuAfXRKap7fdgcCY5uykM6+R9GqQ8K/ux8P/C5b2E8x2U6sQ=="
+  crossorigin="anonymous"
+></script>
+```
+
+The browser verifies the hash of the loaded resource. If it does not match, the resource is blocked. Generate hashes with: `openssl dgst -sha384 -binary file.js | openssl base64 -A`.
+
+### Dependency Auditing
+
+Third-party dependencies are the most underestimated attack surface. The 2021 Log4Shell vulnerability and 2022 node-ipc supply chain attack demonstrated that a dependency in a dependency can cause a critical vulnerability.
+
+**Baseline practices:**
+- Run `npm audit` or `pnpm audit` in CI — fail the build on critical/high severities
+- Pin exact dependency versions in production builds (lockfile required)
+- Review dependency additions as carefully as code additions
+- Subscribe to security advisories for critical dependencies (GitHub Dependabot, Snyk)
+
+## Deep Guidance
+
+### Content Security Policy Implementation
+
+Deploying CSP in production requires a staged approach — a strict policy will break things:
+
+**Phase 1: Report-only mode.** Use `Content-Security-Policy-Report-Only` with a `report-uri` endpoint. This logs violations without blocking anything. Collect violations for 1–2 weeks.
+
+**Phase 2: Fix violations.** Address inline scripts (move to external files or use nonces), fix disallowed origins, and handle third-party widget requirements.
+
+**Phase 3: Enforce.** Switch to `Content-Security-Policy`. Monitor violation reports for regressions.
+
+```typescript
+// Next.js CSP with nonces (recommended over 'unsafe-inline')
+import { headers } from 'next/headers';
+import crypto from 'crypto';
+
+export default function RootLayout({ children }) {
+  const nonce = crypto.randomBytes(16).toString('base64');
+
+  const cspHeader = [
+    `default-src 'self'`,
+    `script-src 'self' 'nonce-${nonce}' 'strict-dynamic'`,
+    `style-src 'self' 'nonce-${nonce}'`,
+    `img-src 'self' blob: data: https:`,
+    `font-src 'self'`,
+    `object-src 'none'`,
+    `base-uri 'self'`,
+    `form-action 'self'`,
+    `frame-ancestors 'none'`,
+    `upgrade-insecure-requests`,
+  ].join('; ');
+
+  return (
+    <html>
+      <head>
+        <meta httpEquiv="Content-Security-Policy" content={cspHeader} />
+      </head>
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+
+### Security Headers Checklist
+
+Every production web app must serve these response headers:
+
+```
+# Prevent clickjacking
+Content-Security-Policy: frame-ancestors 'none'
+X-Frame-Options: DENY  # Legacy browsers
+
+# Prevent MIME sniffing
+X-Content-Type-Options: nosniff
+
+# Enable HSTS (HTTP Strict Transport Security)
+Strict-Transport-Security: max-age=63072000; includeSubDomains; preload
+
+# Control referrer information
+Referrer-Policy: strict-origin-when-cross-origin
+
+# Control browser features
+Permissions-Policy: camera=(), microphone=(), geolocation=()
+
+# Prevent IE compatibility mode
+X-UA-Compatible: IE=edge
+```
+
+Configure these in your CDN (Cloudflare, Vercel, Fastly) or reverse proxy rather than application code — they should apply to all responses including static assets.
+
+### HTML Sanitization for User Content
+
+When you must render user-supplied HTML (rich text editors, markdown with HTML), use a server-side sanitization library:
+
+```typescript
+import DOMPurify from 'isomorphic-dompurify';
+
+// GOOD: Sanitize before storage and before rendering
+function sanitizeUserHTML(html: string): string {
+  return DOMPurify.sanitize(html, {
+    ALLOWED_TAGS: ['p', 'strong', 'em', 'ul', 'ol', 'li', 'a', 'br', 'blockquote'],
+    ALLOWED_ATTR: ['href', 'target', 'rel'],
+    FORBID_ATTR: ['style', 'class', 'id'],
+    ADD_ATTR: ['rel'],  // Ensure all links have rel="noopener noreferrer"
+    FORCE_BODY: true,
+  });
+}
+
+// BAD: Rendering user HTML without sanitization
+function UnsafeComponent({ userContent }) {
+  return <div dangerouslySetInnerHTML={{ __html: userContent }} />; // XSS risk
+}
+
+// GOOD: Sanitize before rendering
+function SafeComponent({ userContent }) {
+  return <div dangerouslySetInnerHTML={{ __html: sanitizeUserHTML(userContent) }} />;
+}
+```
+
+**Always add `rel="noopener noreferrer"` to user-supplied links.** Without `noopener`, the linked page can access `window.opener` and redirect the original tab.
+
+### OWASP Top 10 Mapping
+
+| OWASP 2021 | Web App Mitigation |
+|---|---|
+| A01 Broken Access Control | Server-side authz on every endpoint; never trust client-claimed identity |
+| A02 Cryptographic Failures | TLS everywhere; never store passwords in plaintext; use bcrypt/Argon2 |
+| A03 Injection | Parameterized queries; ORM; never concatenate user input into SQL/shell commands |
+| A04 Insecure Design | Threat model before building auth/payment flows |
+| A05 Security Misconfiguration | Headers checklist; disable debug endpoints in production; rotate default credentials |
+| A06 Vulnerable Components | `npm audit` in CI; Dependabot alerts; pin lockfile |
+| A07 Auth Failures | PKCE; rate limiting on login; MFA; session timeout |
+| A08 Software Integrity | SRI for CDN assets; verify npm package checksums; signed commits |
+| A09 Logging Failures | Log auth events; alert on anomalies; never log passwords or tokens |
+| A10 SSRF | Validate and restrict URLs in server-side fetch calls; block private IP ranges |
+
+Run a security review against this checklist before the first production deployment and after any major auth or data flow change.

package/content/knowledge/web-app/web-app-session-patterns.md

@@ -0,0 +1,214 @@
+---
+name: web-app-session-patterns
+description: Session management architecture, JWT vs cookie sessions, refresh token rotation, session storage, and hijacking prevention
+topics: [web-app, auth, sessions, jwt, cookies, security, redis]
+---
+
+Session management is the mechanism by which a web application recognizes a returning user between HTTP requests. Because HTTP is stateless, sessions are an application-level construct — and the design decisions here directly affect security, scalability, and user experience. The wrong session architecture causes token theft, session fixation attacks, memory exhaustion on the server, and logout failures that leave users permanently authenticated even after they believe they've signed out.
+
+## Summary
+
+### JWT vs Cookie Sessions
+
+The two primary session patterns have fundamentally different security models:
+
+**Cookie-based sessions (server-authoritative):**
+- Server stores session state (database or Redis); client holds an opaque session ID in a cookie
+- Immediate revocation: delete the session record and the user is logged out
+- Scales horizontally when session storage is centralized (Redis cluster)
+- HttpOnly + Secure + SameSite=Strict cookies resist XSS and CSRF simultaneously
+- Each request requires a session store lookup — adds latency (~1–5 ms for Redis)
+
+**JWT (stateless):**
+- Server stores no session state; the signed token is the complete session
+- No revocation without a token denylist (which re-introduces statefulness)
+- Zero session store lookups per request — appropriate for stateless microservices
+- Tokens can be stolen and reused until expiry — short expiry (15 minutes) is essential
+- Refresh tokens enable long sessions without long-lived access tokens
+
+**Rule of thumb:** Use cookie-based sessions for user-facing web apps where revocation matters. Use JWTs for service-to-service auth or APIs where clients are trusted and revocation is not required. Hybrid: short-lived JWTs + server-side refresh token rotation is the most common production pattern.
+
+### Refresh Token Rotation
+
+Refresh token rotation is the critical security mechanism for long-lived JWT sessions:
+
+1. Access token expires in 15 minutes
+2. Client uses refresh token to obtain a new access token + new refresh token
+3. The old refresh token is immediately invalidated
+4. If the old refresh token is ever presented again, all sessions for that user are terminated (token reuse detection indicates theft)
+
+This pattern detects token theft: if an attacker steals a refresh token and uses it, the legitimate user's next refresh attempt will fail and force re-authentication, alerting the user and invalidating the attacker's session.
+
+### Session Storage Backends
+
+| Backend | Best For | Limits |
+|---|---|---|
+| Redis (single node) | Fast sessions, moderate scale | Single point of failure |
+| Redis Cluster | High availability, large scale | Operational complexity |
+| Redis Sentinel | Automatic failover for single-node Redis | Less scale than Cluster |
+| Database (PostgreSQL) | Simpler stack, queryable sessions | Higher latency than Redis |
+| In-process memory | Development only | Lost on restart, no horizontal scale |
+
+For production, Redis is the standard choice: sub-millisecond lookups, TTL-based expiry is native, and session invalidation is an O(1) DEL command.
+
+### Token Expiry Strategy
+
+Define expiry per token type based on risk tolerance:
+
+- **Access token**: 15 minutes — short enough to limit exposure if stolen
+- **Refresh token**: 7–30 days — rotate on each use; invalidate on logout
+- **Remember-me token**: 90 days — separate from standard refresh, requires stronger audit
+- **Email verification token**: 24–48 hours — single-use, invalidate on consumption
+- **Password reset token**: 1 hour — single-use, invalidate on consumption, invalidate all sessions on use
+
+## Deep Guidance
+
+### Secure Cookie Configuration
+
+Every session cookie must be configured with all three security attributes:
+
+```typescript
+// Express.js session cookie configuration
+app.use(session({
+  name: '__Host-sessionId',  // __Host- prefix requires Secure + path=/ + no domain
+  secret: process.env.SESSION_SECRET,
+  resave: false,
+  saveUninitialized: false,
+  cookie: {
+    httpOnly: true,       // Inaccessible to JavaScript — prevents XSS token theft
+    secure: true,         // HTTPS only — prevents transmission over HTTP
+    sameSite: 'strict',   // Not sent on cross-site requests — prevents CSRF
+    maxAge: 7 * 24 * 60 * 60 * 1000,  // 7 days in milliseconds
+    path: '/',
+  },
+  store: new RedisStore({ client: redisClient }),
+}));
+```
+
+The `__Host-` cookie name prefix is a browser-enforced security policy that prevents subdomain hijacking — it requires `Secure`, `path=/`, and no `Domain` attribute. Use it for session cookies in production.
+
+### Refresh Token Rotation Implementation
+
+```typescript
+interface TokenPair {
+  accessToken: string;
+  refreshToken: string;
+  accessTokenExpiresAt: Date;
+}
+
+async function rotateRefreshToken(
+  incomingRefreshToken: string
+): Promise<TokenPair> {
+  // 1. Look up the incoming refresh token
+  const storedToken = await db.refreshToken.findUnique({
+    where: { token: incomingRefreshToken },
+    include: { user: true },
+  });
+
+  if (!storedToken) {
+    // Token not found — could be expired, already rotated, or forged
+    throw new AuthError('INVALID_REFRESH_TOKEN');
+  }
+
+  if (storedToken.usedAt !== null) {
+    // REUSE DETECTED: token was already rotated — potential theft
+    // Invalidate ALL refresh tokens for this user
+    await db.refreshToken.updateMany({
+      where: { userId: storedToken.userId },
+      data: { revokedAt: new Date() },
+    });
+    throw new AuthError('TOKEN_REUSE_DETECTED');
+  }
+
+  if (storedToken.revokedAt !== null || storedToken.expiresAt < new Date()) {
+    throw new AuthError('REFRESH_TOKEN_EXPIRED');
+  }
+
+  // 2. Mark old token as used (not deleted — needed for reuse detection)
+  await db.refreshToken.update({
+    where: { id: storedToken.id },
+    data: { usedAt: new Date() },
+  });
+
+  // 3. Issue new token pair
+  const newAccessToken = signAccessToken({ sub: storedToken.userId });
+  const newRefreshToken = await db.refreshToken.create({
+    data: {
+      userId: storedToken.userId,
+      token: generateSecureToken(),
+      expiresAt: addDays(new Date(), 30),
+      parentTokenId: storedToken.id,  // Track rotation chain
+    },
+  });
+
+  return {
+    accessToken: newAccessToken,
+    refreshToken: newRefreshToken.token,
+    accessTokenExpiresAt: addMinutes(new Date(), 15),
+  };
+}
+```
+
+### Session Hijacking Prevention
+
+Beyond secure cookies, defend against session hijacking at the application layer:
+
+**IP binding (optional, use carefully):**
+- Store the client IP at session creation and validate on each request
+- Breaks for legitimate users on mobile networks (IP changes per cell tower)
+- Use only for high-security flows (admin panels, bank-grade apps), not general user sessions
+
+**User-Agent fingerprint:**
+- Store a hash of the User-Agent string at session creation
+- Validate on each request; suspicious changes invalidate the session
+- Not a strong defense (UA is spoofable) but raises the cost of attack
+
+**Session fixation prevention:**
+- Always regenerate the session ID on successful authentication
+- Never allow the session ID to be set via URL parameters (cookie-only)
+- In Express: call `req.session.regenerate()` after successful login
+
+**Concurrent session limits:**
+- Track active session count per user in Redis
+- On new login, offer the user the choice to log out other sessions or enforce a maximum
+- Essential for compliance in regulated industries
+
+### Redis Session Store with TTL
+
+```typescript
+import Redis from 'ioredis';
+import RedisStore from 'connect-redis';
+
+const redisClient = new Redis({
+  host: process.env.REDIS_HOST,
+  port: 6379,
+  // Lazy connect — don't block startup if Redis is temporarily unavailable
+  lazyConnect: true,
+  // Retry strategy — exponential backoff
+  retryStrategy: (times: number) => Math.min(times * 50, 2000),
+});
+
+// Sessions expire automatically via Redis TTL — no cleanup job needed
+const sessionStore = new RedisStore({
+  client: redisClient,
+  prefix: 'sess:',
+  ttl: 7 * 24 * 60 * 60,  // 7 days in seconds
+});
+
+// Invalidate a specific session (logout)
+async function invalidateSession(sessionId: string): Promise<void> {
+  await redisClient.del(`sess:${sessionId}`);
+}
+
+// Invalidate all sessions for a user (force logout everywhere)
+async function invalidateAllUserSessions(userId: string): Promise<void> {
+  // Requires storing a user→sessions index in Redis
+  const sessionIds = await redisClient.smembers(`user:sessions:${userId}`);
+  if (sessionIds.length > 0) {
+    await redisClient.del(...sessionIds.map(id => `sess:${id}`));
+    await redisClient.del(`user:sessions:${userId}`);
+  }
+}
+```
+
+Maintain a `user:sessions:{userId}` Redis set to enable "logout everywhere" — essential for security incident response.