# Cache Security and Scope Audit

Use this reference before endorsing any caching-strategy addition or change, when reviewing authenticated/PII route handling, opaque cross-origin response caching, or `scope`/`Service-Worker-Allowed`/cache-versioning coverage. This is the hard-gate section of the skill — findings here are blockers, not style notes.

## What people get wrong

The common bad assumption is:

> "It worked fine when I tested it, so the caching is safe."

Wrong, and dangerously so for shared/multi-account devices. A service worker's Cache API store is per-origin and persists across navigations and sessions — it has no built-in concept of "which user" a cached response belongs to. If an authenticated route (`/api/user`, `/api/account`, `/api/orders/:id`) is cached with any strategy that reads before checking identity, a single-session manual test will look correct while silently setting up cross-user data disclosure the moment a second user logs in on the same device without a full cache purge. This is not a hypothetical: it is the single most severe class of finding this skill exists to catch, and it is invisible to functional QA that only ever tests with one account.

## Non-negotiables

- Do not endorse caching a response containing `Set-Cookie`, an echoed `Authorization` header/token value, or clearly PII/payment-bearing JSON, under any performance justification. The correct strategy for such a route is `NetworkOnly` or explicit exclusion from every `registerRoute`/`urlPattern` matcher — not a "short TTL" compromise.
- Do not endorse a `scope` broader than the routes the service worker is meant to control. `scope` is set at `register()` time (`navigator.serviceWorker.register(url, { scope })`) and defines the maximum set of URLs the worker can intercept; a worker registered at `/` when it only needs to control `/app/` unnecessarily expands the blast radius of every other finding in this file.
- `Service-Worker-Allowed` is a response header needed only when the service-worker *script* itself is served from a path outside the desired scope (e.g., script at `/sw.js` needs to control `/app/`, requiring the server to send `Service-Worker-Allowed: /app/` on the script response). Confirm it is present and no broader than necessary whenever the script path and intended scope diverge.
- Flag `cache.put()` on an opaque (`no-cors`, cross-origin) response as an unreviewable-content risk per OWASP cache-poisoning guidance applied to Cache API misuse: an opaque response's status and headers cannot be inspected by the calling JS, so a `404`, an error page, or a compromised/poisoned upstream response can be cached and served as if it were a valid `200` indefinitely, with zero visibility from the caching code.
- Do not accept "we'll purge the cache manually if this becomes a problem" as a mitigation for authenticated-data caching. There is no reliable trigger for "manually" here — the fix is not caching it in the first place.

## Minimal safe audit flow

1. Enumerate every route matcher and cross-reference against `route-classification-matrix.md` to identify which, if any, are classified authenticated/PII.
2. For every authenticated/PII route, confirm the applied strategy is `NetworkOnly` or that the route is excluded from all matchers (i.e., falls through to the browser's normal network path with no service-worker interception at all).
3. Open DevTools → Application → Cache Storage (or run the equivalent inspection command in an automated check) and manually inspect actual cached entries — do not trust config intent alone. Look for any entry whose URL matches an authenticated/PII route class, and for any response body containing session tokens, emails, names, or account identifiers that shouldn't be persisted client-side.
4. Confirm `scope` at registration matches the intended coverage, and `Service-Worker-Allowed` (if applicable) is no broader.
5. Confirm a versioned cache-name scheme exists (e.g., `app-cache-v3`) and that `activate` either calls `cleanupOutdatedCaches()` (Workbox precaching) or manually deletes cache keys not in the current manifest/version — an unbounded, unversioned cache cannot be reliably rolled back or purged.
6. Confirm any `cache.put()` call on a cross-origin request is not operating on an opaque response, or is explicitly justified and reviewed if it must be (e.g., a trusted, pinned third-party origin with documented risk acceptance).

## Adversarial checklist

Before signing off on any caching-strategy change, answer these:

- Is every authenticated/PII route verified excluded by inspecting actual cached entries in DevTools, not just by reading the strategy config?
- If this device is shared or a second user logs in without a full logout/cache-clear, can any previously cached response leak across accounts?
- Does `scope` match only what this worker needs to control, verified against the actual `register()` call, not assumed from the script's file location?
- Is there a versioned cache-name and `activate`-time cleanup path, verified by checking that an old-version cache key actually gets deleted after a version bump — not just present in code but unexercised?
- Is every `cache.put()` on a cross-origin request either non-opaque (`cors` mode with an inspectable response) or explicitly justified?

If any of these cannot be answered from direct evidence (config read, DevTools inspection, or explicit user-provided confirmation), the finding is a residual risk, not a pass.

## When to push back

Push back if the user asks for:

- caching an authenticated API response "just for this one screen" to make it feel faster — the risk is identical regardless of scope of use,
- a broader `scope` than the app actually needs "in case we add more routes later" — expand scope when the need is real, not speculatively,
- skipping the DevTools cache-entry inspection step because "the config looks right" — config intent and actual cached content diverge often enough (matcher bugs, stale test data, prior strategy still in a live cache) that this step is not optional.

# Route Classification and Strategy Matrix

Use this reference when mapping a concrete route inventory (the actual `registerRoute`/`urlPattern` matchers in the service worker or Workbox config) to a caching strategy per class, and when a review needs to justify why one class gets a different strategy than another.

## What people get wrong

The common bad assumption is:

> "We picked a caching strategy for the service worker" — as if one strategy applies to the whole app.

Wrong. A service worker's `fetch` handler intercepts every request type in its scope — HTML navigations, API calls, images, fonts, scripts — and each has a different freshness contract and a different security profile. A single copy-pasted strategy (almost always `CacheFirst`, lifted from a tutorial about caching fonts) applied uniformly is the single most common defect this skill exists to catch. It is not "faster" across the board; it is wrong for at least two of the four classes below in nearly every real app.

## Non-negotiable design rule: classify before you judge

Before ruling on any single `registerRoute`/`runtimeCaching` entry, classify every matched route into one of these buckets. A strategy is only correct or incorrect *relative to its class* — there is no universally "best" strategy.

## Route class → strategy matrix

| Route class | Example | Correct default strategy | Why |
|---|---|---|---|
| Static asset, content-hashed filename | `/assets/app.a1b2c3.js`, webfonts | Precache (`precacheAndRoute`) or `CacheFirst` with long `maxAgeSeconds` | Immutable — a content change produces a new URL, so serving a stale cached copy under the old URL is impossible by construction. |
| Static asset, NOT content-hashed | `/logo.png`, `/favicon.ico` | `StaleWhileRevalidate` with `ExpirationPlugin` | Can change without a URL change; needs periodic revalidation, but instant-from-cache is still safe since content is non-sensitive. |
| Navigation / HTML (app shell, document requests) | `/`, `/dashboard` (document destination) | `StaleWhileRevalidate` or `NetworkFirst` (short `networkTimeoutSeconds`) — never blind `CacheFirst` | Blind cache-first strands users on a stale app shell after every deploy, since the HTML entry point is how new asset references reach the client at all. |
| API GET, public/non-sensitive | `/api/public-catalog` | `StaleWhileRevalidate` or `NetworkFirst` with short TTL (`ExpirationPlugin.maxAgeSeconds`) | Needs freshness bounded by business tolerance for staleness; non-sensitive, so caching itself is not a security concern — only staleness is. |
| API GET, authenticated/PII-bearing | `/api/user`, `/api/account`, `/api/orders/:id` | `NetworkOnly`, or explicit exclusion from any `registerRoute` match entirely | Hard security block — see `cache-security-and-scope-audit.md`. No performance justification overrides this. |
| API mutation (POST/PUT/PATCH/DELETE) | any write endpoint | Not cacheable by Cache API spec (GET-only); verify no workaround exists | If a manual `cache.put()` appears on a mutation response, that is a code smell requiring explanation on its own, independent of strategy choice. |
| Cross-origin, third-party, `no-cors` | third-party widgets, uncontrolled CDNs | Avoid `cache.put()` on the resulting opaque response, or scope tightly with clear justification | Opaque responses cannot be inspected for status/headers — see `cache-security-and-scope-audit.md`. |

## Verification targets

- Enumerate every `registerRoute`/`urlPattern` matcher in the file/config under review and assign it exactly one row from the matrix above — an unassignable route (matches nothing cleanly) is itself a finding: the matcher is probably too broad.
- For each matcher, confirm the *matcher itself* is scoped correctly — a regex like `/^\/api\//` bundling public and authenticated endpoints under one strategy is a classification bug even before the strategy choice is evaluated.
- Confirm no single strategy declaration (e.g., one `CacheFirst` block) is reused across more than one route class without an explicit justification for why that class's freshness/security needs happen to coincide.

## High-risk assumptions to kill

- "One strategy for the whole app is simpler to maintain" — simplicity here trades directly against both stale-deploy incidents and cross-user data leakage; the per-class matrix is the actual minimum safe design, not an optional refinement.
- "It's a GET request, so it's safe to cache" — GET-only is a Cache API constraint, not a security guarantee; `/api/user` is a GET and is exactly the kind of route that must never be cache-first.
- "The tutorial cached fonts with CacheFirst, so CacheFirst is the safe default" — `CacheFirst` is only safe for the specific class (immutable/rarely-changing, non-sensitive) the tutorial was written for.

## When to push back

Push back if the user asks to:

- apply one strategy across the whole `fetch` handler "to keep the config simple,"
- cache an authenticated or account-scoped API route with any strategy other than `NetworkOnly`/exclusion, regardless of the performance rationale offered,
- skip per-route classification because "it's basically all API calls" — read/write and public/authenticated are not the same bucket even when the URL prefix is shared.

# Workbox Strategy Semantics

Use this reference when a review needs to confirm the exact runtime behavior of a caching strategy — precache vs. `CacheFirst` vs. `NetworkFirst` vs. `StaleWhileRevalidate` vs. `NetworkOnly` — or the Vite-PWA `generateSW`/`injectManifest` config surface that produces it, before ruling on whether it matches a route's freshness/security needs.

## What people get wrong

The common bad assumption is:

> "Precaching is just cache-first for build assets."

Incomplete, and dangerous when carried into a security review. Per Workbox v7 source (`workbox-precaching/src/PrecacheStrategy.ts`, confirmed via Context7 against `/googlechrome/workbox`), `precacheAndRoute()` registers a `PrecacheRoute` whose `_handle` calls `handler.cacheMatch(request)` and **returns immediately on a hit — no network request, no revalidation, no HTTP involvement at all**. That is not "cache-first that also checks freshness sometimes" — it is a pure Cache API read with zero interaction with `Cache-Control`, `ETag`, or `Vary`. A runtime `CacheFirst` strategy is a different, separate mechanism: it also serves from cache on a hit, but falls through to a real network fetch (and populates the cache) on a miss. Treating the two as interchangeable in a finding misattributes which HTTP headers matter and which don't.

> Version note: Workbox internals are version-sensitive. Confirm exact behavior against the installed Workbox major version via Context7 (`/googlechrome/workbox`) or the live `https://developer.chrome.com/docs/workbox/` docs before ruling — do not cite this file's summaries as the final word for an unverified version.

## Officially grounded strategy shape

Per Workbox docs/source (Context7-confirmed):

- **Precache (`precacheAndRoute`)** — build-time-known, content-hashed assets. Served from Cache API with no revalidation, no HTTP cache-control involvement. Correct only for immutable, versioned assets where the precache manifest itself is the freshness mechanism (a new manifest = new cache entries).
- **`CacheFirst` (recipe/strategy)** — checks cache; on hit, returns immediately (no revalidation on hit, same as precache once cached); on miss, fetches network and populates cache. Per the Workbox Recipes README, this is "ideal for assets that rarely change, such as fonts or images" — not for anything that can change without a URL change.
- **`StaleWhileRevalidate`** — serves the cached response immediately if present, then makes a network request in the background to update the cache for the *next* request. Balances performance and freshness; the response returned to this request can still be stale by one cycle.
- **`NetworkFirst`** — attempts network first (optionally bounded by `networkTimeoutSeconds`); falls back to cache only on network failure/timeout. Appropriate for content that must be fresh when possible but should still work offline/flaky-network.
- **`NetworkOnly`** — never touches the cache for this route. Use for anything that must never be served stale or never be persisted client-side (mutations, authenticated reads that are hard-blocked from caching).
- **`ExpirationPlugin`** (`maxEntries`, `maxAgeSeconds`) — bounds a runtime cache's size/age; without it, a runtime cache used with `CacheFirst`/`StaleWhileRevalidate`/`NetworkFirst` grows unbounded. This does not apply to precache, which is version-bounded by the manifest itself.
- **`cleanupOutdatedCaches`** (`workbox-precaching`) — removes precache caches from prior manifest versions on activate. Confirm this (or equivalent manual `activate`-event cache deletion, as shown in Vite-PWA's `injectManifest` example querying `manifestURLs` and deleting non-listed keys) is present before endorsing any precache-based strategy.

## Vite-PWA config surface (when in use)

- `generateSW` strategy: `runtimeCaching` array maps `urlPattern` → `handler` (`'CacheFirst'`, `'NetworkFirst'`, `'StaleWhileRevalidate'`, `'NetworkOnly'`, etc.) + `options` (`cacheName`, `expiration`, `cacheableResponse`). Confirm every `runtimeCaching` entry's `urlPattern` is scoped tightly enough that it does not accidentally net authenticated API routes into a `CacheFirst` bucket meant for fonts/static assets.
- `injectManifest` strategy: a custom `sw.ts`/`sw.js` source, precache manifest injected via `self.__WB_MANIFEST`. Review the custom source directly — Vite-PWA does not add any safety net here; every strategy choice, `activate` cleanup, and `skipWaiting`/`clientsClaim()` call is entirely the author's responsibility.
- `clientsClaim()` + `self.skipWaiting()` — needed so a newly activated service worker takes control of open clients immediately rather than waiting for a full reload; absence of these (or an equivalent deliberate "update available, reload?" UX) means users can be stuck on stale app-shell logic indefinitely even after a successful deploy.

## Verification targets

- Confirm the strategy name in code/config against this file's semantics table, then confirm current behavior via Context7 before finalizing — do not rely on the strategy's *name* alone (e.g., "NetworkFirst" implementations have varied `networkTimeoutSeconds` defaults across versions).
- For any runtime-cached route, confirm an `ExpirationPlugin` (or Vite-PWA `expiration` option) is present with a `maxAgeSeconds`/`maxEntries` bound appropriate to the route's sensitivity and volatility.
- For precache, confirm `cleanupOutdatedCaches` or equivalent manual `activate` cleanup runs so superseded manifest versions are purged.

## High-risk assumptions to kill

- "Precache is basically cache-first" — precache bypasses HTTP entirely; runtime `CacheFirst` still makes a real network request on a cache miss.
- "`StaleWhileRevalidate` means the user always gets fresh data" — the response served to the *current* request can be a stale copy; freshness only improves for the *next* request.
- "No `ExpirationPlugin` is fine, the cache will sort itself out" — Cache API storage does not auto-evict; unbounded runtime caches grow until storage quota pressure causes browser-driven eviction, which is unpredictable and not a substitute for a deliberate policy.
- "We use `generateSW`, so Vite-PWA handles safety for us" — `generateSW` only wires the strategy the author picked in `runtimeCaching`; it does not choose a safe strategy per route automatically or exclude authenticated routes on its own.