@j0hanz/superfetch 2.5.2 → 2.6.0

package/dist/cache.js

@@ -1,61 +1,46 @@
+import { EventEmitter } from 'node:events';
+import { posix as pathPosix } from 'node:path';
+import { z } from 'zod';
 import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { ErrorCode, McpError, SubscribeRequestSchema, UnsubscribeRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
 import { config } from './config.js';
 import { sha256Hex } from './crypto.js';
 import { getErrorMessage } from './errors.js';
 import { stableStringify as stableJsonStringify } from './json.js';
-import { logDebug, logWarn } from './observability.js';
-import { isObject } from './type-guards.js';
+import { logWarn } from './observability.js';
 /* -------------------------------------------------------------------------------------------------
- * Cached payload codec
+ * Schemas & Types
  * ------------------------------------------------------------------------------------------------- */
-function hasOptionalStringProperty(value, key) {
-    const prop = value[key];
-    return prop === undefined ? true : typeof prop === 'string';
-}
-function isCachedPayload(value) {
-    if (!isObject(value))
-        return false;
-    if (!hasOptionalStringProperty(value, 'content'))
-        return false;
-    if (!hasOptionalStringProperty(value, 'markdown'))
-        return false;
-    if (!hasOptionalStringProperty(value, 'title'))
-        return false;
-    return true;
-}
-class CachedPayloadCodec {
-    parse(raw) {
-        try {
-            const parsed = JSON.parse(raw);
-            return isCachedPayload(parsed) ? parsed : null;
-        }
-        catch {
-            return null;
-        }
+const CacheNamespace = z.literal('markdown');
+const HashString = z
+    .string()
+    .regex(/^[a-f0-9.]+$/i)
+    .min(8)
+    .max(64);
+const CachedPayloadSchema = z.strictObject({
+    content: z.string().optional(),
+    markdown: z.string().optional(),
+    title: z.string().optional(),
+});
+/* -------------------------------------------------------------------------------------------------
+ * Core: Cache Key Logic
+ * ------------------------------------------------------------------------------------------------- */
+const CACHE_CONSTANTS = {
+    URL_HASH_LENGTH: 32,
+    VARY_HASH_LENGTH: 16,
+};
+export function parseCachedPayload(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        return CachedPayloadSchema.parse(parsed);
     }
-    resolveContent(payload) {
-        if (typeof payload.markdown === 'string')
-            return payload.markdown;
-        if (typeof payload.content === 'string')
-            return payload.content;
+    catch {
         return null;
     }
 }
-const payloadCodec = new CachedPayloadCodec();
-export function parseCachedPayload(raw) {
-    return payloadCodec.parse(raw);
-}
 export function resolveCachedPayloadContent(payload) {
-    return payloadCodec.resolveContent(payload);
+    return payload.markdown ?? payload.content ?? null;
 }
-/* -------------------------------------------------------------------------------------------------
- * Cache key codec (hashing + parsing + resource URI)
- * ------------------------------------------------------------------------------------------------- */
-const CACHE_HASH = {
-    URL_HASH_LENGTH: 32,
-    VARY_HASH_LENGTH: 16,
-};
 function stableStringify(value) {
     try {
         return stableJsonStringify(value);
@@ -72,183 +57,122 @@ function buildCacheKey(namespace, urlHash, varyHash) {
         ? `${namespace}:${urlHash}.${varyHash}`
         : `${namespace}:${urlHash}`;
 }
-function getVaryHash(vary) {
-    if (!vary)
-        return undefined;
-    const varyString = typeof vary === 'string' ? vary : stableStringify(vary);
-    if (varyString === null)
+export function createCacheKey(namespace, url, vary) {
+    if (!namespace || !url)
         return null;
-    if (!varyString)
-        return undefined;
-    return createHashFragment(varyString, CACHE_HASH.VARY_HASH_LENGTH);
-}
-function buildCacheResourceUri(namespace, urlHash) {
-    return `superfetch://cache/${namespace}/${urlHash}`;
-}
-class CacheKeyCodec {
-    create(namespace, url, vary) {
-        if (!namespace || !url)
-            return null;
-        const urlHash = createHashFragment(url, CACHE_HASH.URL_HASH_LENGTH);
-        const varyHash = getVaryHash(vary);
-        if (varyHash === null)
-            return null;
-        return buildCacheKey(namespace, urlHash, varyHash);
-    }
-    parse(cacheKey) {
-        if (!cacheKey)
-            return null;
-        const [namespace, ...rest] = cacheKey.split(':');
-        const urlHash = rest.join(':');
-        if (!namespace || !urlHash)
-            return null;
-        return { namespace, urlHash };
-    }
-    toResourceUri(cacheKey) {
-        const parts = this.parse(cacheKey);
-        if (!parts)
+    const urlHash = createHashFragment(url, CACHE_CONSTANTS.URL_HASH_LENGTH);
+    let varyHash;
+    if (vary) {
+        const varyString = typeof vary === 'string' ? vary : stableStringify(vary);
+        if (varyString === null)
             return null;
-        return buildCacheResourceUri(parts.namespace, parts.urlHash);
+        if (varyString) {
+            varyHash = createHashFragment(varyString, CACHE_CONSTANTS.VARY_HASH_LENGTH);
+        }
     }
-}
-const cacheKeyCodec = new CacheKeyCodec();
-export function createCacheKey(namespace, url, vary) {
-    return cacheKeyCodec.create(namespace, url, vary);
+    return buildCacheKey(namespace, urlHash, varyHash);
 }
 export function parseCacheKey(cacheKey) {
-    return cacheKeyCodec.parse(cacheKey);
+    if (!cacheKey)
+        return null;
+    const [namespace, ...rest] = cacheKey.split(':');
+    const urlHash = rest.join(':');
+    if (!namespace || !urlHash)
+        return null;
+    return { namespace, urlHash };
 }
 export function toResourceUri(cacheKey) {
-    return cacheKeyCodec.toResourceUri(cacheKey);
+    const parts = parseCacheKey(cacheKey);
+    if (!parts)
+        return null;
+    return `superfetch://cache/${parts.namespace}/${parts.urlHash}`;
 }
 /* -------------------------------------------------------------------------------------------------
- * In-memory LRU cache (native)
- * Contract:
- * - Max entries: config.cache.maxKeys
- * - TTL in ms: config.cache.ttl * 1000
- * - Access does NOT extend TTL
+ * Core: In-Memory Store
  * ------------------------------------------------------------------------------------------------- */
-class NativeLruCache {
-    max;
-    ttlMs;
-    entries = new Map();
-    nextPurgeAtMs = 0;
-    constructor({ max, ttlMs }) {
-        this.max = max;
-        this.ttlMs = ttlMs;
-    }
-    get(key) {
-        const entry = this.entries.get(key);
-        if (!entry)
-            return undefined;
-        if (this.isExpired(entry, Date.now())) {
-            this.entries.delete(key);
-            return undefined;
-        }
-        // Refresh LRU order without extending TTL.
-        this.entries.delete(key);
-        this.entries.set(key, entry);
-        return entry.value;
-    }
-    set(key, value) {
-        if (this.max <= 0 || this.ttlMs <= 0)
-            return;
-        const now = Date.now();
-        this.entries.delete(key);
-        this.entries.set(key, { value, expiresAtMs: now + this.ttlMs });
-        this.maybePurge(now);
-        while (this.entries.size > this.max) {
-            const oldestKey = this.entries.keys().next().value;
-            if (oldestKey === undefined)
-                break;
-            this.entries.delete(oldestKey);
-        }
-    }
-    keys() {
-        this.maybePurge(Date.now());
-        return [...this.entries.keys()];
-    }
-    maybePurge(now) {
-        if (this.entries.size > this.max || now >= this.nextPurgeAtMs) {
-            this.purgeExpired(now);
-            this.nextPurgeAtMs = now + this.ttlMs;
-        }
-    }
-    purgeExpired(now) {
-        for (const [key, entry] of this.entries) {
-            if (this.isExpired(entry, now))
-                this.entries.delete(key);
-        }
-    }
-    isExpired(entry, now) {
-        return entry.expiresAtMs <= now;
-    }
-}
 class InMemoryCacheStore {
-    cache = new NativeLruCache({
-        max: config.cache.maxKeys,
-        ttlMs: config.cache.ttl * 1000,
-    });
-    listeners = new Set();
+    max = config.cache.maxKeys;
+    ttlMs = config.cache.ttl * 1000;
+    entries = new Map();
+    updateEmitter = new EventEmitter();
     isEnabled() {
         return config.cache.enabled;
     }
     keys() {
-        return [...this.cache.keys()];
+        if (!this.isEnabled())
+            return [];
+        const now = Date.now();
+        return Array.from(this.entries.entries())
+            .filter(([, entry]) => entry.expiresAtMs > now)
+            .map(([key]) => key);
     }
     onUpdate(listener) {
-        this.listeners.add(listener);
-        return () => this.listeners.delete(listener);
+        const wrapped = (event) => {
+            try {
+                const result = listener(event);
+                if (result instanceof Promise) {
+                    void result.catch((error) => {
+                        this.logError('Cache update listener failed (async)', event.cacheKey, error);
+                    });
+                }
+            }
+            catch (error) {
+                this.logError('Cache update listener failed', event.cacheKey, error);
+            }
+        };
+        this.updateEmitter.on('update', wrapped);
+        return () => {
+            this.updateEmitter.off('update', wrapped);
+        };
     }
-    get(cacheKey) {
-        if (!this.isReadable(cacheKey))
+    get(cacheKey, options) {
+        if (!cacheKey || (!this.isEnabled() && !options?.force))
             return undefined;
-        return this.run(cacheKey, 'Cache get error', () => this.cache.get(cacheKey));
-    }
-    set(cacheKey, content, metadata) {
-        if (!this.isWritable(cacheKey, content))
-            return;
-        this.run(cacheKey, 'Cache set error', () => {
-            const now = Date.now();
-            const expiresAtMs = now + config.cache.ttl * 1000; // preserve existing behavior
-            const entry = this.buildEntry(content, metadata, now, expiresAtMs);
-            this.cache.set(cacheKey, entry);
-            this.notify(cacheKey);
-        });
-    }
-    isReadable(cacheKey) {
-        return config.cache.enabled && Boolean(cacheKey);
-    }
-    isWritable(cacheKey, content) {
-        return config.cache.enabled && Boolean(cacheKey) && Boolean(content);
-    }
-    run(cacheKey, message, operation) {
-        try {
-            return operation();
-        }
-        catch (error) {
-            this.logError(message, cacheKey, error);
+        const entry = this.entries.get(cacheKey);
+        if (!entry)
+            return undefined;
+        if (entry.expiresAtMs <= Date.now()) {
+            this.entries.delete(cacheKey);
             return undefined;
         }
+        // Refresh LRU position
+        this.entries.delete(cacheKey);
+        this.entries.set(cacheKey, entry);
+        return entry;
     }
-    buildEntry(content, metadata, fetchedAtMs, expiresAtMs) {
-        return {
+    set(cacheKey, content, metadata, options) {
+        if (!cacheKey || !content)
+            return;
+        if (!this.isEnabled() && !options?.force)
+            return;
+        const now = Date.now();
+        const expiresAtMs = now + this.ttlMs;
+        const entry = {
             url: metadata.url,
             content,
-            fetchedAt: new Date(fetchedAtMs).toISOString(),
+            fetchedAt: new Date(now).toISOString(),
             expiresAt: new Date(expiresAtMs).toISOString(),
-            ...(metadata.title === undefined ? {} : { title: metadata.title }),
+            expiresAtMs,
+            ...(metadata.title ? { title: metadata.title } : {}),
         };
+        this.entries.delete(cacheKey);
+        this.entries.set(cacheKey, entry);
+        // Eviction
+        if (this.entries.size > this.max) {
+            const firstKey = this.entries.keys().next();
+            if (!firstKey.done) {
+                this.entries.delete(firstKey.value);
+            }
+        }
+        this.notify(cacheKey);
     }
     notify(cacheKey) {
-        if (this.listeners.size === 0)
-            return;
-        const parts = cacheKeyCodec.parse(cacheKey);
-        if (!parts)
+        if (this.updateEmitter.listenerCount('update') === 0)
             return;
-        const event = { cacheKey, ...parts };
-        for (const listener of this.listeners)
-            listener(event);
+        const parts = parseCacheKey(cacheKey);
+        if (parts) {
+            this.updateEmitter.emit('update', { cacheKey, ...parts });
+        }
     }
     logError(message, cacheKey, error) {
         logWarn(message, {
@@ -257,15 +181,17 @@ class InMemoryCacheStore {
         });
     }
 }
+// Singleton Instance
 const store = new InMemoryCacheStore();
+// Public Proxy API
 export function onCacheUpdate(listener) {
     return store.onUpdate(listener);
 }
-export function get(cacheKey) {
-    return store.get(cacheKey);
+export function get(cacheKey, options) {
+    return store.get(cacheKey, options);
 }
-export function set(cacheKey, content, metadata) {
-    store.set(cacheKey, content, metadata);
+export function set(cacheKey, content, metadata, options) {
+    store.set(cacheKey, content, metadata, options);
 }
 export function keys() {
     return store.keys();
@@ -274,361 +200,213 @@ export function isEnabled() {
     return store.isEnabled();
 }
 /* -------------------------------------------------------------------------------------------------
- * MCP cached content resource (superfetch://cache/markdown/{urlHash})
+ * Adapter: MCP Cached Content Resource
  * ------------------------------------------------------------------------------------------------- */
-const CACHE_NAMESPACE = 'markdown';
-const HASH_PATTERN = /^[a-f0-9.]+$/i;
-const INVALID_CACHE_PARAMS_MESSAGE = 'Invalid cache resource parameters';
-function throwInvalidCacheParams() {
-    throw new McpError(ErrorCode.InvalidParams, INVALID_CACHE_PARAMS_MESSAGE);
-}
-function resolveStringParam(value) {
-    return typeof value === 'string' ? value : null;
-}
-function isValidNamespace(namespace) {
-    return namespace === CACHE_NAMESPACE;
-}
-function isValidHash(hash) {
-    return HASH_PATTERN.test(hash) && hash.length >= 8 && hash.length <= 64;
-}
-function requireRecordParams(value) {
-    if (!isObject(value))
-        throwInvalidCacheParams();
-    return value;
-}
-function requireParamString(params, key) {
-    const resolved = resolveStringParam(params[key]);
-    if (!resolved) {
-        throw new McpError(ErrorCode.InvalidParams, 'Both namespace and urlHash parameters are required');
-    }
-    return resolved;
-}
-function resolveCacheParams(params) {
-    const parsed = requireRecordParams(params);
-    const namespace = requireParamString(parsed, 'namespace');
-    const urlHash = requireParamString(parsed, 'urlHash');
-    if (!isValidNamespace(namespace) || !isValidHash(urlHash)) {
-        throwInvalidCacheParams();
-    }
-    return { namespace, urlHash };
-}
-function isValidCacheResourceUri(uri) {
-    if (!uri)
-        return false;
-    let parsed;
-    try {
-        parsed = new URL(uri);
-    }
-    catch {
-        return false;
-    }
-    if (parsed.protocol !== 'superfetch:')
-        return false;
-    if (parsed.hostname !== 'cache')
-        return false;
-    const parts = parsed.pathname.split('/').filter(Boolean);
-    if (parts.length !== 2)
-        return false;
-    const [namespace, urlHash] = parts;
-    if (!namespace || !urlHash)
-        return false;
-    return isValidNamespace(namespace) && isValidHash(urlHash);
-}
-function buildResourceEntry(namespace, urlHash) {
-    return {
+const CacheResourceParamsSchema = z.object({
+    namespace: CacheNamespace,
+    urlHash: HashString,
+});
+function listCachedResources() {
+    const resources = store
+        .keys()
+        .map((key) => parseCacheKey(key))
+        .filter((parts) => parts !== null && parts.namespace === 'markdown')
+        .map(({ namespace, urlHash }) => ({
         name: `${namespace}:${urlHash}`,
-        uri: buildCacheResourceUri(namespace, urlHash),
+        uri: `superfetch://cache/${namespace}/${urlHash}`,
         description: `Cached content entry for ${namespace}`,
         mimeType: 'text/markdown',
-    };
-}
-function listCachedResources() {
-    const resources = keys()
-        .map((key) => {
-        const parts = cacheKeyCodec.parse(key);
-        if (parts?.namespace !== CACHE_NAMESPACE)
-            return null;
-        return buildResourceEntry(parts.namespace, parts.urlHash);
-    })
-        .filter((entry) => entry !== null);
+    }));
     return { resources };
 }
-function appendServerOnClose(server, handler) {
-    const previousOnClose = server.server.onclose;
-    server.server.onclose = () => {
-        previousOnClose?.();
-        handler();
-    };
-}
-function attachInitializedGate(server) {
-    let initialized = false;
-    const previousInitialized = server.server.oninitialized;
-    server.server.oninitialized = () => {
-        initialized = true;
-        previousInitialized?.();
-    };
-    return () => initialized;
-}
-function getClientResourceCapabilities(server) {
-    const caps = server.server.getClientCapabilities();
-    if (!caps || !isObject(caps))
-        return { listChanged: false, subscribe: false };
-    const { resources } = caps;
-    if (!isObject(resources))
-        return { listChanged: false, subscribe: false };
-    const { listChanged, subscribe } = resources;
-    return { listChanged: listChanged === true, subscribe: subscribe === true };
+function resolveCachedMarkdownText(raw) {
+    if (!raw)
+        return null;
+    const payload = parseCachedPayload(raw);
+    if (payload)
+        return resolveCachedPayloadContent(payload);
+    const trimmed = raw.trimStart();
+    if (trimmed.startsWith('{') || trimmed.startsWith('['))
+        return null;
+    return raw;
 }
-function registerResourceSubscriptionHandlers(server) {
+export function registerCachedContentResource(server, serverIcons) {
+    // Resource Registration
+    server.registerResource('cached-content', new ResourceTemplate('superfetch://cache/{namespace}/{urlHash}', {
+        list: listCachedResources,
+    }), {
+        title: 'Cached Content',
+        description: 'Access previously fetched web content from cache.',
+        mimeType: 'text/markdown',
+        ...(serverIcons ? { icons: serverIcons } : {}),
+    }, (uri, params) => {
+        const parsed = CacheResourceParamsSchema.safeParse(params);
+        if (!parsed.success) {
+            throw new McpError(ErrorCode.InvalidParams, 'Invalid resource parameters');
+        }
+        const { namespace, urlHash } = parsed.data;
+        const cacheKey = `${namespace}:${urlHash}`;
+        const cached = store.get(cacheKey, { force: true });
+        if (!cached) {
+            throw new McpError(-32002, `Content not found: ${cacheKey}`);
+        }
+        const text = resolveCachedMarkdownText(cached.content);
+        if (!text) {
+            throw new McpError(ErrorCode.InternalError, 'Cached content invalid');
+        }
+        return {
+            contents: [{ uri: uri.href, mimeType: 'text/markdown', text }],
+        };
+    });
+    // Subscriptions
     const subscriptions = new Set();
-    server.server.setRequestHandler(SubscribeRequestSchema, (request) => {
-        const { uri } = request.params;
-        if (!isValidCacheResourceUri(uri)) {
+    server.server.setRequestHandler(SubscribeRequestSchema, (req) => {
+        if (isValidCacheUri(req.params.uri)) {
+            subscriptions.add(req.params.uri);
+        }
+        else {
             throw new McpError(ErrorCode.InvalidParams, 'Invalid resource URI');
         }
-        subscriptions.add(uri);
         return {};
     });
-    server.server.setRequestHandler(UnsubscribeRequestSchema, (request) => {
-        const { uri } = request.params;
-        if (!isValidCacheResourceUri(uri)) {
+    server.server.setRequestHandler(UnsubscribeRequestSchema, (req) => {
+        if (isValidCacheUri(req.params.uri)) {
+            subscriptions.delete(req.params.uri);
+        }
+        else {
             throw new McpError(ErrorCode.InvalidParams, 'Invalid resource URI');
         }
-        subscriptions.delete(uri);
         return {};
     });
-    appendServerOnClose(server, () => {
-        subscriptions.clear();
-    });
-    return subscriptions;
-}
-function notifyResourceUpdate(server, uri, subscriptions) {
-    if (!server.isConnected())
-        return;
-    if (!subscriptions.has(uri))
-        return;
-    void server.server.sendResourceUpdated({ uri }).catch((error) => {
-        logWarn('Failed to send resource update notification', {
-            uri,
-            error: getErrorMessage(error),
-        });
-    });
-}
-function requireCacheEntry(cacheKey) {
-    const cached = get(cacheKey);
-    if (!cached) {
-        throw new McpError(-32002, `Content not found in cache for key: ${cacheKey}`);
-    }
-    return cached;
-}
-function buildMarkdownContentResponse(uri, content) {
-    const payload = payloadCodec.parse(content);
-    const resolvedContent = payload ? payloadCodec.resolveContent(payload) : null;
-    if (!resolvedContent) {
-        throw new McpError(ErrorCode.InternalError, 'Cached markdown content is missing');
-    }
-    return {
-        contents: [
-            { uri: uri.href, mimeType: 'text/markdown', text: resolvedContent },
-        ],
+    // Notifications
+    let initialized = false;
+    const originalOnInitialized = server.server.oninitialized;
+    server.server.oninitialized = () => {
+        initialized = true;
+        originalOnInitialized?.();
     };
-}
-function buildCachedContentResponse(uri, cacheKey) {
-    const cached = requireCacheEntry(cacheKey);
-    return buildMarkdownContentResponse(uri, cached.content);
-}
-function registerCacheContentResource(server, serverIcons) {
-    server.registerResource('cached-content', new ResourceTemplate('superfetch://cache/{namespace}/{urlHash}', {
-        list: listCachedResources,
-    }), {
-        title: 'Cached Content',
-        description: 'Access previously fetched web content from cache. Namespace: markdown. UrlHash: SHA-256 hash of the URL.',
-        mimeType: 'text/markdown',
-        ...(serverIcons ? { icons: serverIcons } : {}),
-    }, (uri, params) => {
-        const { namespace, urlHash } = resolveCacheParams(params);
-        const cacheKey = `${namespace}:${urlHash}`;
-        return buildCachedContentResponse(uri, cacheKey);
-    });
-}
-function registerCacheUpdateSubscription(server, subscriptions, isInitialized) {
-    const unsubscribe = onCacheUpdate(({ cacheKey }) => {
-        if (!server.isConnected() || !isInitialized())
+    store.onUpdate(({ cacheKey }) => {
+        if (!server.isConnected() || !initialized)
             return;
-        const { listChanged, subscribe } = getClientResourceCapabilities(server);
-        if (subscribe) {
-            const resourceUri = cacheKeyCodec.toResourceUri(cacheKey);
-            if (resourceUri)
-                notifyResourceUpdate(server, resourceUri, subscriptions);
+        // Check capabilities via unsafe cast or helper (SDK limitation)
+        const capabilities = server.server.getClientCapabilities();
+        const uri = toResourceUri(cacheKey);
+        if (capabilities?.resources?.subscribe && uri && subscriptions.has(uri)) {
+            void server.server
+                .sendResourceUpdated({ uri })
+                .catch((error) => {
+                logWarn('Failed to send update', {
+                    uri,
+                    error: getErrorMessage(error),
+                });
+            });
         }
-        if (listChanged) {
-            server.sendResourceListChanged();
+        if (capabilities?.resources?.listChanged) {
+            void server.server.sendResourceListChanged().catch(() => { });
         }
     });
-    appendServerOnClose(server, unsubscribe);
-}
-export function registerCachedContentResource(server, serverIcons) {
-    const isInitialized = attachInitializedGate(server);
-    const subscriptions = registerResourceSubscriptionHandlers(server);
-    registerCacheContentResource(server, serverIcons);
-    registerCacheUpdateSubscription(server, subscriptions, isInitialized);
-}
-/* -------------------------------------------------------------------------------------------------
- * Filename generation
- * ------------------------------------------------------------------------------------------------- */
-const MAX_FILENAME_LENGTH = 200;
-const UNSAFE_CHARS_REGEX = /[<>:"/\\|?*]|\p{C}/gu;
-const WHITESPACE_REGEX = /\s+/g;
-function trimHyphens(value) {
-    let start = 0;
-    let end = value.length;
-    while (start < end && value[start] === '-')
-        start += 1;
-    while (end > start && value[end - 1] === '-')
-        end -= 1;
-    return value.slice(start, end);
 }
-function stripCommonPageExtension(segment) {
-    return segment.replace(/\.(html?|php|aspx?|jsp)$/i, '');
-}
-function normalizeUrlFilenameSegment(segment) {
-    const cleaned = stripCommonPageExtension(segment);
-    if (!cleaned)
-        return null;
-    if (cleaned === 'index')
-        return null;
-    return cleaned;
-}
-function getLastPathSegment(url) {
-    const segments = url.pathname.split('/').filter(Boolean);
-    if (segments.length === 0)
-        return null;
-    return segments[segments.length - 1] ?? null;
-}
-function extractFilenameFromUrl(url) {
+function isValidCacheUri(uri) {
     try {
-        const urlObj = new URL(url);
-        const lastSegment = getLastPathSegment(urlObj);
-        if (!lastSegment)
-            return null;
-        return normalizeUrlFilenameSegment(lastSegment);
+        const url = new URL(uri);
+        if (url.protocol !== 'superfetch:' || url.hostname !== 'cache')
+            return false;
+        if (url.search || url.hash)
+            return false;
+        const parts = url.pathname.split('/').filter(Boolean);
+        return parts.length === 2 && parts[0] === 'markdown';
     }
     catch {
-        return null;
+        return false;
     }
 }
-function slugifyTitle(title) {
-    const slug = title
+/* -------------------------------------------------------------------------------------------------
+ * Utils: Filename Logic
+ * ------------------------------------------------------------------------------------------------- */
+const FILENAME_RULES = {
+    MAX_LEN: 200,
+    UNSAFE_CHARS: /[<>:"/\\|?*\p{C}]/gu,
+    WHITESPACE: /\s+/g,
+    EXTENSIONS: /\.(html?|php|aspx?|jsp)$/i,
+};
+function sanitizeString(input) {
+    return input
         .toLowerCase()
-        .trim()
-        .replace(UNSAFE_CHARS_REGEX, '')
-        .replace(WHITESPACE_REGEX, '-')
-        .replace(/-+/g, '-');
-    const trimmed = trimHyphens(slug);
-    return trimmed || null;
-}
-function sanitizeFilename(name, extension) {
-    let sanitized = name
-        .replace(UNSAFE_CHARS_REGEX, '')
-        .replace(WHITESPACE_REGEX, '-')
-        .trim();
-    const maxBase = MAX_FILENAME_LENGTH - extension.length;
-    if (sanitized.length > maxBase) {
-        sanitized = sanitized.substring(0, maxBase);
-    }
-    return `${sanitized}${extension}`;
+        .replace(FILENAME_RULES.UNSAFE_CHARS, '')
+        .replace(FILENAME_RULES.WHITESPACE, '-')
+        .replace(/-+/g, '-')
+        .replace(/(?:^-|-$)/g, '');
 }
 export function generateSafeFilename(url, title, hashFallback, extension = '.md') {
-    const fromUrl = extractFilenameFromUrl(url);
-    if (fromUrl)
-        return sanitizeFilename(fromUrl, extension);
-    if (title) {
-        const fromTitle = slugifyTitle(title);
-        if (fromTitle)
-            return sanitizeFilename(fromTitle, extension);
-    }
-    if (hashFallback) {
-        return `${hashFallback.substring(0, 16)}${extension}`;
-    }
-    return `download-${Date.now()}${extension}`;
-}
-function parseDownloadParams(namespace, hash) {
-    const resolvedNamespace = resolveStringParam(namespace);
-    const resolvedHash = resolveStringParam(hash);
-    if (!resolvedNamespace || !resolvedHash)
-        return null;
-    if (!isValidNamespace(resolvedNamespace))
-        return null;
-    if (!isValidHash(resolvedHash))
-        return null;
-    return { namespace: resolvedNamespace, hash: resolvedHash };
-}
-function buildCacheKeyFromParams(params) {
-    return `${params.namespace}:${params.hash}`;
-}
-function sendJsonError(res, status, error, code) {
-    res.writeHead(status, { 'Content-Type': 'application/json' });
-    res.end(JSON.stringify({ error, code }));
-}
-function respondBadRequest(res, message) {
-    sendJsonError(res, 400, message, 'BAD_REQUEST');
-}
-function respondNotFound(res) {
-    sendJsonError(res, 404, 'Content not found or expired', 'NOT_FOUND');
-}
-function respondServiceUnavailable(res) {
-    sendJsonError(res, 503, 'Download service is disabled', 'SERVICE_UNAVAILABLE');
-}
-function buildContentDisposition(fileName) {
-    const encodedName = encodeURIComponent(fileName).replace(/'/g, '%27');
-    return `attachment; filename="${fileName}"; filename*=UTF-8''${encodedName}`;
-}
-function sendDownloadPayload(res, payload) {
-    const disposition = buildContentDisposition(payload.fileName);
-    res.setHeader('Content-Type', payload.contentType);
-    res.setHeader('Content-Disposition', disposition);
-    res.setHeader('Cache-Control', `private, max-age=${config.cache.ttl}`);
-    res.setHeader('X-Content-Type-Options', 'nosniff');
-    res.end(payload.content);
-}
-function resolveDownloadPayload(params, cacheEntry) {
-    const payload = payloadCodec.parse(cacheEntry.content);
-    if (!payload)
-        return null;
-    const content = payloadCodec.resolveContent(payload);
-    if (!content)
-        return null;
-    const safeTitle = typeof payload.title === 'string' ? payload.title : undefined;
-    const fileName = generateSafeFilename(cacheEntry.url, cacheEntry.title ?? safeTitle, params.hash, '.md');
-    return {
-        content,
-        contentType: 'text/markdown; charset=utf-8',
-        fileName,
+    const tryUrl = () => {
+        try {
+            if (!URL.canParse(url))
+                return null;
+            const parsed = new URL(url);
+            if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:')
+                return null;
+            const { pathname } = parsed;
+            const basename = pathPosix.basename(pathname);
+            if (!basename || basename === 'index')
+                return null;
+            const cleaned = basename.replace(FILENAME_RULES.EXTENSIONS, '');
+            const sanitized = sanitizeString(cleaned);
+            if (sanitized === 'index')
+                return null;
+            return sanitized || null;
+        }
+        catch {
+            return null;
+        }
     };
+    const tryTitle = () => {
+        if (!title)
+            return null;
+        return sanitizeString(title) || null;
+    };
+    const name = tryUrl() ??
+        tryTitle() ??
+        hashFallback?.substring(0, 16) ??
+        `download-${Date.now()}`;
+    const maxBase = FILENAME_RULES.MAX_LEN - extension.length;
+    const truncated = name.length > maxBase ? name.substring(0, maxBase) : name;
+    return `${truncated}${extension}`;
 }
+/* -------------------------------------------------------------------------------------------------
+ * Adapter: Download Handler
+ * ------------------------------------------------------------------------------------------------- */
+const DownloadParamsSchema = z.object({
+    namespace: CacheNamespace,
+    hash: HashString,
+});
 export function handleDownload(res, namespace, hash) {
-    if (!config.cache.enabled) {
-        respondServiceUnavailable(res);
-        return;
-    }
-    const params = parseDownloadParams(namespace, hash);
-    if (!params) {
-        respondBadRequest(res, 'Invalid namespace or hash format');
+    const respond = (status, msg, code) => {
+        res.writeHead(status, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: msg, code }));
+    };
+    const parsed = DownloadParamsSchema.safeParse({ namespace, hash });
+    if (!parsed.success) {
+        respond(400, 'Invalid namespace or hash', 'BAD_REQUEST');
         return;
     }
-    const cacheKey = buildCacheKeyFromParams(params);
-    const cacheEntry = get(cacheKey);
-    if (!cacheEntry) {
-        logDebug('Download request for missing cache key', { cacheKey });
-        respondNotFound(res);
+    const cacheKey = `${parsed.data.namespace}:${parsed.data.hash}`;
+    const entry = store.get(cacheKey, { force: true });
+    if (!entry) {
+        respond(404, 'Not found or expired', 'NOT_FOUND');
         return;
     }
-    const payload = resolveDownloadPayload(params, cacheEntry);
-    if (!payload) {
-        logDebug('Download payload unavailable', { cacheKey });
-        respondNotFound(res);
+    const payload = parseCachedPayload(entry.content);
+    const content = payload ? resolveCachedPayloadContent(payload) : null;
+    if (!content) {
+        respond(404, 'Content missing', 'NOT_FOUND');
         return;
     }
-    logDebug('Serving download', { cacheKey, fileName: payload.fileName });
-    sendDownloadPayload(res, payload);
+    const fileName = generateSafeFilename(entry.url, payload?.title, parsed.data.hash);
+    // Safe header generation
+    const encoded = encodeURIComponent(fileName).replace(/'/g, '%27');
+    res.setHeader('Content-Type', 'text/markdown; charset=utf-8');
+    res.setHeader('Content-Disposition', `attachment; filename="${fileName}"; filename*=UTF-8''${encoded}`);
+    res.setHeader('Cache-Control', `private, max-age=${config.cache.ttl}`);
+    res.setHeader('X-Content-Type-Options', 'nosniff');
+    res.end(content);
 }