Mandatory Partitioning and Credential Isolation for W3C Speculation Rules API

--- description: Mandatory Partitioning and Credential Isolation for W3C Speculation Rules API - Enforces strict isolation, anonymous credential modes, and Sec-Purpose headers validation when using the W3C Speculation Rules API for prefetching and prerendering. Prevents cross-site information leaks (XS-Leaks), speculative timing attacks, and CSRF/state mutation via unpartitioned cross-origin speculative fetching. globs: src/**/*.{ts,tsx,js,jsx}, public/**/*.html, server/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/speculation-rules-cross-origin-partitioning-standard" --- # Mandatory Partitioning and Credential Isolation for W3C Speculation Rules API > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Unrestricted Credentialed Speculative Execution Across Origins Without Partitioning Guards ## System Constraints You are a Principal Security Architect enforcing safe usage of the W3C Speculation Rules API. Speculative prerendering and prefetching must never leak authenticated state, mutate server-side state, or establish unpartitioned cross-origin cache side-channels. Mandate anonymous credential modes, strictly isolate cross-origin speculation targets, and enforce server-side validation against prefetching state-modifying routes. ## Strict Guidelines - Engineers MUST ALWAYS set `requires: ["anonymous-client-ip-when-cross-origin"]` or explicit credential omission when configuring cross-origin speculative rules. - Engineers MUST NOT configure prerender rules (`source: "list"` or `source: "document"`) pointing to cross-origin endpoints unless the target origin explicitly serves matching `Supports-Loading-Mode: credentialed-prerender` headers and strict partitioning is acknowledged. - Engineers MUST NEVER speculatively prefetch or prerender HTTP routes that perform state mutations (GET routes that trigger side-effects, session resets, or transaction writes). - Code SHOULD dynamically inject `<script type="speculationrules">` only after sanitizing target URLs against an explicit allowlist of idempotent, read-only origin endpoints. - Services MUST inspect incoming HTTP headers for `Sec-Purpose: prefetch` or `Sec-Purpose: prerender` and drop/reject any requests that attempt side-effects, tracking increments, or authenticated state alterations during speculative execution. - Components NEVER attach wildcard speculation rules (e.g., `href_matches: "/*"`) without explicit negative selector constraints excluding logout, checkout, OAuth, and API routes. ## Bad vs Good Implementations ### Speculation Rule Script Injection with Cross-Origin Partitioning Guards #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Injecting candidate URLs without filtering allows cross-origin targets to receive authenticated cookies and client IPs, opening XS-Leak side-channels. Furthermore, prerendering non-idempotent or cross-origin URLs can cause unauthorized state mutations and CSRF vulnerabilities. ```typescript // VULNERABLE: Indiscriminate prefetching and prerendering across origins with full credentials export function injectSpeculationRules(candidateUrls: string[]): void { const script = document.createElement('script'); script.type = 'speculationrules'; script.textContent = JSON.stringify({ prefetch: [ { source: 'list', urls: candidateUrls // Leaks user cookies and IP to cross-origin targets; exposes XS-Leak } ], prerender: [ { source: 'list', urls: candidateUrls // May execute state-mutating requests (e.g., /logout, /checkout) } ] }); document.head.appendChild(script); } ``` #### Production Standard (Correct) > **Standard**: Sanitizes speculative candidate URLs to exclude mutable operations (auth, checkout, api), confines prerenders to safe local origins, and explicitly sets anonymous IP/credential protection requirements to avoid cross-origin side channels. ```typescript // SECURE: Partitioned, credential-isolated speculation rules with explicit route exclusions interface SpeculationRulesConfig { prefetchUrls: string[]; prerenderUrls: string[]; trustedOrigin: string; } export function injectSafeSpeculationRules(config: SpeculationRulesConfig): void { const isSafeRelativeUrl = (url: string): boolean => { try { const parsed = new URL(url, window.location.origin); const isExcluded = /\/(api|auth|logout|checkout|admin)(\/|$)/i.test(parsed.pathname); return parsed.origin === window.location.origin && !isExcluded; } catch { return false; } }; const safePrefetch = config.prefetchUrls.filter(isSafeRelativeUrl); const safePrerender = config.prerenderUrls.filter(isSafeRelativeUrl); const rules = { prefetch: [ { source: 'list', urls: safePrefetch, requires: ['anonymous-client-ip-when-cross-origin'] } ], prerender: [ { source: 'list', urls: safePrerender, eagerness: 'conservative' } ] }; const script = document.createElement('script'); script.type = 'speculationrules'; script.textContent = JSON.stringify(rules); document.head.appendChild(script); } ``` ### Server-Side Middleware Guarding Against Speculative Side-Effects #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: If a browser speculatively prerenders this GET route, user deactivation will execute silently in a speculative execution context without user intent. ```typescript // VULNERABLE: Express/Node route executing side-effects during speculative prefetch/prerender import { Request, Response } from 'express'; export function handleAccountDeactivation(req: Request, res: Response): void { // Insecure GET with side-effect vulnerable to speculative prerender execution const userId = req.session.userId; deactivateUser(userId); res.status(200).json({ status: 'deactivated' }); } ``` #### Production Standard (Correct) > **Standard**: Middleware explicitly checks the Sec-Purpose header to halt speculative requests from hitting sensitive logic, and enforces non-idempotent HTTP verbs for all state modifications. ```typescript // SECURE: Rejecting state mutation on speculative requests and verifying HTTP idempotency import { Request, Response, NextFunction } from 'express'; export function blockSpeculativeExecution(req: Request, res: Response, next: NextFunction): void { const purpose = req.header('Sec-Purpose') || req.header('Purpose'); const isSpeculative = purpose && /prerender|prefetch/i.test(purpose); if (isSpeculative) { // 503 or 425 Early Hints prevents caching or executing unprompted speculative actions res.status(425).set('Cache-Control', 'no-store').send('Speculative execution disallowed on this resource'); return; } next(); } export function handleAccountDeactivation(req: Request, res: Response): void { // State changes MUST require POST/DELETE with CSRF verification if (req.method !== 'POST') { res.status(405).json({ error: 'Method Not Allowed' }); return; } deactivateUser(req.session.userId); res.status(200).json({ status: 'deactivated' }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Mandatory Partitioning and Credential Isolation for W3C Speculation Rules API

Mandatory Partitioning and Credential Isolation for W3C Speculation Rules API defines an industrial-grade behavioral standard for frontend engineering. Enforces strict isolation, anonymous credential modes, and Sec-Purpose headers validation when using the W3C Speculation Rules API for prefetching and prerendering. Prevents cross-site information leaks (XS-Leaks), speculative timing attacks, and CSRF/state mutation via unpartitioned cross-origin speculative fetching. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Unrestricted Credentialed Speculative Execution Across Origins Without Partitioning Guards Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Unrestricted Credentialed Speculative Execution Across Origins Without Partitioning Guards	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST ALWAYS set `requires

Engineers MUST ALWAYS set `requires: ["anonymous-client-ip-when-cross-origin"]` or explicit credential omission when configuring cross-origin speculative rules.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.