Fix cache key collisions, HTTP scheme mixing, and Vary ambiguity

.changeset/cache-key-overhaul.md

@@ -0,0 +1,13 @@
+---
+'@web-widget/shared-cache': major
+---
+
+Fix cache key safety, HTTP semantics, and Vary handling:
+
+- **Reduce wrong cache hits from digest collisions** — cookie/header/device values are hashed with a single standard SHA-1 digest over a canonical string, instead of per-value truncated digests that could collide at scale.
+- **Stop `http` and `https` from sharing the same entry** — URL scheme is included in default keys so representations are not mixed across schemes (RFC 9111 URI identity).
+- **Make Vary-aware keys unambiguous** — use explicit `|v|` / `|vary|` suffixes so base keys, Vary metadata, and variants cannot be parsed incorrectly.
+- **Keep keys debuggable without exposing secrets** — fragment key names stay visible (`#cookie:a|header:x-id@…`); only normalized values are digested.
+- **Align cache lookup options with Workers Cache API** — `match()` / `delete()` support `ignoreMethod` only; ignore query strings via `cacheKeyRules.search: false`, and bypass Vary via `sharedCache.ignoreVary`.
+
+**Breaking:** Existing cache entries miss until they expire or are revalidated. Set `scheme: false` to keep the previous host-first URL shape. Remove `cacheKeyPartDefiners` / `SharedCacheKeyPartDefiners`; use built-in `cacheKeyRules` only.

README.md

@@ -692,13 +692,7 @@ sharedCache: {
 }
 ```
 
-**Default cache key rules:**
-
-```typescript
-{
-  search: true,
-}
-```
+**Default cache key rules:** `scheme`, `host`, `pathname`, and `search` are all enabled. Keys look like `https://example.com/path?a=1`. Set `scheme: false` only if a reverse proxy always presents `http:` internally.
 
 ### Cache Key Components
 
@@ -1256,24 +1250,7 @@ interface Cache {
 
 **Options Parameter Differences:**
 
-SharedCache's `CacheQueryOptions` interface differs from the standard Web Cache API:
-
-```typescript
-interface CacheQueryOptions {
-  ignoreSearch?: boolean; // ❌ Not implemented - throws error
-  ignoreMethod?: boolean; // ✅ Supported
-  ignoreVary?: boolean; // ❌ Not implemented - throws error
-}
-```
-
-**Supported Options:**
-
-- **✅ `ignoreMethod`**: Treat request as GET regardless of actual HTTP method
-
-**Unsupported Options (throw errors):**
-
-- **❌ `ignoreSearch`**: Query string handling not customizable
-- **❌ `ignoreVary`**: Vary header processing not bypassable (Note: This option is actually supported in SharedCache)
+`match()` and `delete()` support `ignoreMethod` only—the same subset as the [Cloudflare Workers Cache API](https://developers.cloudflare.com/workers/runtime-apis/cache/). To ignore query strings, set `cacheKeyRules.search: false`. To bypass Vary processing, set `sharedCache.ignoreVary: true`.
 
 ### 📊 Compliance Summary
 
@@ -1287,7 +1264,7 @@ interface CacheQueryOptions {
 ### 🛡️ Production-Grade Implementation
 
 - **Professional HTTP Semantics**: Powered by `http-cache-semantics` for RFC compliance
-- **Intelligent Cache Strategies**: Advanced cache key generation with URL normalization
+- **Configurable Cache Keys**: Rules for URL parts, cookies, headers, and custom fragments
 - **Robust Error Handling**: Comprehensive exception handling with graceful degradation
 - **Performance Optimized**: Efficient storage backends with configurable TTL