@endday/search-mcp 1.0.0

package/src/platform/auth.impl.js

@@ -0,0 +1,166 @@
+import { env } from "../../envs.js";
+import { ApiError } from "../core/errors.js";
+import { validateSession, getSessionIdFromRequest } from "./session.js";
+import { enforceRateLimit } from "./rateLimit.js";
+
+function matchesConfigSet(value, allowedValues) {
+  return allowedValues.includes(
+    String(value || "").trim().toLowerCase()
+  );
+}
+
+const TRUTHY_CONFIG_VALUES = ["1", "true", "yes", "on", "required"];
+
+function getBearerToken(request) {
+  return request.headers.get("Authorization")?.replace(/^Bearer\s+/i, "");
+}
+
+function getRequestToken(request, paramToken) {
+  return getBearerToken(request) || request.headers.get("x-api-key") || paramToken;
+}
+
+function isAuthRequired() {
+  return !!env.TOKEN || isTruthyConfig(env.AUTH_REQUIRED);
+}
+
+function isTruthyConfig(value) {
+  return matchesConfigSet(value, TRUTHY_CONFIG_VALUES);
+}
+
+function isAuthorizedToken(requestToken) {
+  if (!isAuthRequired()) {
+    return true;
+  }
+  return !!env.TOKEN && requestToken === env.TOKEN;
+}
+
+/**
+ * Unified authentication: checks token OR session cookie.
+ * Returns { authenticated, method } where method is 'token', 'session', or 'none'.
+ */
+export async function authenticateRequest(request, params = {}) {
+  // If auth is not required at all, allow immediately
+  if (!isAuthRequired()) {
+    return { authenticated: true, method: "none" };
+  }
+
+  // 1. Check token auth (Authorization header, x-api-key header, or query param)
+  const requestToken = getRequestToken(request, params.token);
+  if (requestToken && isAuthorizedToken(requestToken)) {
+    return { authenticated: true, method: "token", token: requestToken };
+  }
+
+  // 2. Check session cookie
+  const sessionResult = await validateSession(request);
+  if (sessionResult.valid) {
+    return {
+      authenticated: true,
+      method: "session",
+      sessionId: sessionResult.sessionId,
+      setCookie: sessionResult.setCookie,
+    };
+  }
+
+  // 3. Not authenticated - fail closed if AUTH_REQUIRED but no TOKEN configured
+  if (isTruthyConfig(env.AUTH_REQUIRED) && !env.TOKEN) {
+    throw new ApiError({
+      status: 503,
+      code: "AUTH_TOKEN_NOT_CONFIGURED",
+      category: "configuration",
+      message:
+        "AUTH_REQUIRED is enabled but TOKEN is not configured. Set TOKEN before using protected local MCP flows.",
+    });
+  }
+
+  return { authenticated: false, method: "none" };
+}
+
+/**
+ * Get the rate limit key based on auth method.
+ */
+export function getRateLimitKey(authResult) {
+  if (authResult.method === "token") {
+    return authResult.token;
+  }
+  if (authResult.method === "session" && authResult.sessionId) {
+    return `session:${authResult.sessionId}`;
+  }
+  // For unauthenticated, use null (IP-based rate limiting)
+  return null;
+}
+
+export function getRequestClientId(request, authResult, paramToken) {
+  if (authResult?.method === "session" && authResult.sessionId) {
+    return `session:${authResult.sessionId}`;
+  }
+
+  if (authResult?.method === "token" && authResult.token) {
+    return `token:${authResult.token}`;
+  }
+
+  const requestToken = getRequestToken(request, paramToken);
+  if (requestToken && isAuthorizedToken(requestToken)) {
+    return `token:${requestToken}`;
+  }
+
+  const sessionId = getSessionIdFromRequest(request);
+  if (sessionId) {
+    return `session:${sessionId}`;
+  }
+
+  const clientIp =
+    request.headers.get("cf-connecting-ip") ||
+    request.headers.get("x-forwarded-for") ||
+    "anonymous";
+
+  return `ip:${clientIp}`;
+}
+
+/**
+ * Get rate limit token for pre-auth rate limiting.
+ * Returns the token if valid, session ID if cookie present, otherwise null (IP-based).
+ * Fix #7: Session users get their own bucket, not shared with unauthenticated IP users.
+ */
+export function getRateLimitToken(request, paramToken) {
+  if (!isAuthRequired()) {
+    return null;
+  }
+
+  const requestToken = getRequestToken(request, paramToken);
+  if (requestToken && isAuthorizedToken(requestToken)) {
+    return requestToken;
+  }
+
+  // Peek at session cookie without KV validation - gives session users
+  // their own rate limit bucket so they don't share with unauthenticated IPs
+  const sessionId = getSessionIdFromRequest(request);
+  if (sessionId) {
+    return `session:${sessionId}`;
+  }
+
+  return null;
+}
+
+/**
+ * Fix #8: Unified auth+rate-limit helper to eliminate boilerplate duplication.
+ * Rate limits first (prevents brute force), then authenticates.
+ * Returns authResult or throws 401/429.
+ */
+export async function requireAuth(request, params = {}) {
+  await enforceRateLimit(request, getRateLimitToken(request, params.token));
+
+  const authResult = await authenticateRequest(request, params);
+
+  if (!authResult.authenticated) {
+    throw new ApiError({
+      status: 401,
+      code: "UNAUTHORIZED",
+      category: "auth",
+      message: "Authentication required. Provide a valid token or session cookie.",
+    });
+  }
+
+  return authResult;
+}
+
+export { isAuthRequired, isTruthyConfig, matchesConfigSet, getRequestToken, isAuthorizedToken };

package/src/platform/auth.js

@@ -0,0 +1 @@
+export * from "./auth.impl.js";

package/src/platform/cache.impl.js

@@ -0,0 +1,166 @@
+import { env } from "../../envs.js";
+import { sha256Hex } from "../core/crypto.js";
+import { logWarn } from "./logger.js";
+
+const CACHE_PREFIX = "search:v3";
+const EDGE_CACHE_NAMESPACE = "search-edge:v1";
+
+function isKvAvailable() {
+  return !!env.SEARCH_KV && typeof env.SEARCH_KV.get === "function";
+}
+
+function isEdgeCacheAvailable() {
+  return typeof caches !== "undefined" && !!caches.default;
+}
+
+async function getCacheKey({
+  query,
+  requested_engines,
+  engines,
+  language,
+  time_range,
+  pageno,
+}) {
+  const payload = JSON.stringify({
+    query,
+    requested_engines,
+    engines,
+    language,
+    time_range,
+    pageno,
+  });
+  const hash = await sha256Hex(payload);
+  return `${CACHE_PREFIX}:${hash}`;
+}
+
+async function getEdgeCacheKey(searchParams) {
+  const key = await getCacheKey(searchParams);
+  return `${EDGE_CACHE_NAMESPACE}:${key}`;
+}
+
+async function getCachedSearchResponseFromEdge(searchParams) {
+  const ttl = Number.parseInt(env.EDGE_CACHE_TTL_SECONDS || "0", 10);
+  if (!isEdgeCacheAvailable() || ttl <= 0) {
+    return null;
+  }
+
+  try {
+    const cacheKey = await getEdgeCacheKey(searchParams);
+    const response = await caches.default.match(`https://cache.internal/${cacheKey}`);
+    if (!response) {
+      return null;
+    }
+
+    const payload = await response.json();
+    if (!payload?.response) {
+      return null;
+    }
+
+    return {
+      response: payload.response,
+      state: "hit",
+      layer: "edge",
+    };
+  } catch (error) {
+    logWarn("cache.edge_read_failed", {}, error);
+    return null;
+  }
+}
+
+async function setCachedSearchResponseToEdge(searchParams, response) {
+  const ttl = Number.parseInt(env.EDGE_CACHE_TTL_SECONDS || "0", 10);
+  if (!isEdgeCacheAvailable() || ttl <= 0) {
+    return;
+  }
+
+  try {
+    const cacheKey = await getEdgeCacheKey(searchParams);
+    const request = new Request(`https://cache.internal/${cacheKey}`);
+    const payload = new Response(
+      JSON.stringify({
+        response,
+      }),
+      {
+        headers: {
+          "Content-Type": "application/json",
+          "Cache-Control": `max-age=${ttl}`,
+        },
+      }
+    );
+    await caches.default.put(request, payload);
+  } catch (error) {
+    logWarn("cache.edge_write_failed", {}, error);
+  }
+}
+
+export async function getCachedSearchResponse(searchParams) {
+  const edgeEntry = await getCachedSearchResponseFromEdge(searchParams);
+  if (edgeEntry) {
+    return edgeEntry;
+  }
+
+  const ttl = Number.parseInt(env.CACHE_TTL_SECONDS || "0", 10);
+  if (!isKvAvailable() || ttl <= 0) {
+    return null;
+  }
+
+  const key = await getCacheKey(searchParams);
+  const entry = await env.SEARCH_KV.get(key, "json");
+  if (!entry?.response) {
+    return null;
+  }
+
+  const now = Date.now();
+  if (entry.freshUntil > now) {
+    return {
+      response: entry.response,
+      state: "hit",
+      layer: "kv",
+    };
+  }
+
+  if (entry.staleUntil > now) {
+    return {
+      response: entry.response,
+      state: "stale",
+      layer: "kv",
+    };
+  }
+
+  return null;
+}
+
+export async function setCachedSearchResponse(searchParams, response) {
+  await setCachedSearchResponseToEdge(searchParams, response);
+
+  const ttl = Number.parseInt(env.CACHE_TTL_SECONDS || "0", 10);
+  if (!isKvAvailable() || ttl <= 0) {
+    return;
+  }
+
+  const staleTtl = Math.max(
+    0,
+    Number.parseInt(env.STALE_CACHE_TTL_SECONDS || "0", 10)
+  );
+  const now = Date.now();
+  const freshUntil = now + ttl * 1000;
+  const staleUntil = freshUntil + staleTtl * 1000;
+  const key = await getCacheKey(searchParams);
+  await env.SEARCH_KV.put(
+    key,
+    JSON.stringify({
+      response,
+      freshUntil,
+      staleUntil,
+    }),
+    {
+      expirationTtl: ttl + staleTtl,
+    }
+  );
+}
+
+export function createDeferredCachedSearchResponseWriter(searchParams, response) {
+  return async function writeCachedSearchResponse() {
+    await setCachedSearchResponse(searchParams, response);
+  };
+}

package/src/platform/cache.js

@@ -0,0 +1 @@
+export * from "./cache.impl.js";

package/src/platform/health.impl.js

@@ -0,0 +1,133 @@
+import { env } from "../../envs.js";
+import { getStateKv, normalizeExpirationTtl } from "./stateKv.js";
+import { logWarn } from "./logger.js";
+
+const HEALTH_PREFIX = "health:v2";
+const memoryHealthState = new Map();
+
+export function resetHealthState() {
+  memoryHealthState.clear();
+}
+
+function createDefaultEngineState() {
+  return {
+    consecutiveFailures: 0,
+    disabledUntil: 0,
+    lastFailureAt: 0,
+    lastSuccessAt: 0,
+  };
+}
+
+function getHealthKey(engineName) {
+  return `${HEALTH_PREFIX}:${engineName}`;
+}
+
+function getMemoryEngineState(engineName) {
+  if (!memoryHealthState.has(engineName)) {
+    memoryHealthState.set(engineName, createDefaultEngineState());
+  }
+
+  return memoryHealthState.get(engineName);
+}
+
+async function getKvEngineState(kv, engineName) {
+  try {
+    return (await kv.get(getHealthKey(engineName), "json")) || null;
+  } catch (error) {
+    logWarn("health.kv_read_failed", { engine: engineName }, error);
+    return null;
+  }
+}
+
+async function persistEngineState(engineName, state) {
+  const memoryState = getMemoryEngineState(engineName);
+  Object.assign(memoryState, state);
+
+  const kv = getStateKv();
+  if (!kv) {
+    return;
+  }
+
+  try {
+    await kv.put(getHealthKey(engineName), JSON.stringify(state), {
+      expirationTtl: normalizeExpirationTtl(env.HEALTH_STATE_TTL_SECONDS, 3600),
+    });
+  } catch (error) {
+    logWarn("health.kv_write_failed", { engine: engineName }, error);
+  }
+}
+
+async function getEngineState(engineName) {
+  const kv = getStateKv();
+  const kvState = kv ? await getKvEngineState(kv, engineName) : null;
+
+  if (kvState) {
+    return {
+      ...createDefaultEngineState(),
+      ...kvState,
+    };
+  }
+
+  return getMemoryEngineState(engineName);
+}
+
+export async function prioritizeHealthyEngines(engineNames) {
+  const now = Date.now();
+  const healthy = [];
+  const degraded = [];
+  const engineStates = await Promise.all(
+    engineNames.map(async (engineName) => ({
+      engineName,
+      state: await getEngineState(engineName),
+    }))
+  );
+
+  for (const { engineName, state } of engineStates) {
+    if (state.disabledUntil > now) {
+      degraded.push(engineName);
+    } else {
+      healthy.push(engineName);
+    }
+  }
+
+  return healthy.length > 0 ? [...healthy, ...degraded] : [...engineNames];
+}
+
+export async function recordEngineSuccess(engineName) {
+  const state = await getEngineState(engineName);
+  state.consecutiveFailures = 0;
+  state.disabledUntil = 0;
+  state.lastSuccessAt = Date.now();
+  await persistEngineState(engineName, state);
+}
+
+export async function recordEngineFailure(engineName) {
+  const state = await getEngineState(engineName);
+  const failureThreshold = Number.parseInt(
+    env.HEALTH_FAILURE_THRESHOLD || "2",
+    10
+  );
+  const cooldownMs =
+    Number.parseInt(env.HEALTH_COOLDOWN_SECONDS || "180", 10) * 1000;
+
+  state.consecutiveFailures += 1;
+  state.lastFailureAt = Date.now();
+
+  if (state.consecutiveFailures >= failureThreshold) {
+    state.disabledUntil = Date.now() + cooldownMs;
+  }
+
+  await persistEngineState(engineName, state);
+}
+
+export function createDeferredEngineSuccessRecorder(engineName) {
+  return async function recordSuccess() {
+    await recordEngineSuccess(engineName);
+  };
+}
+
+export function createDeferredEngineFailureRecorder(engineName) {
+  return async function recordFailure() {
+    await recordEngineFailure(engineName);
+  };
+}

package/src/platform/health.js

@@ -0,0 +1 @@
+export * from "./health.impl.js";

package/src/platform/http.impl.js

@@ -0,0 +1,108 @@
+import { env } from "../../envs.js";
+import { normalizeError, toErrorPayload } from "../core/errors.js";
+
+const ALLOWED_METHODS = "GET, POST, OPTIONS";
+
+function buildServerTimingHeader(engineTimings) {
+  return engineTimings
+    .map((timing) => `${timing.engine};dur=${timing.duration_ms}`)
+    .join(", ");
+}
+
+function buildTierSummary(engineTimings) {
+  const tiers = new Set();
+  for (const timing of engineTimings) {
+    if (timing?.tier) {
+      tiers.add(String(timing.tier));
+    }
+  }
+
+  return [...tiers].join(",");
+}
+
+export function buildCorsHeaders(request) {
+  const headers = {
+    "Access-Control-Allow-Methods": ALLOWED_METHODS,
+    "Access-Control-Allow-Headers":
+      request.headers.get("Access-Control-Request-Headers") ||
+      env.CORS_ALLOWED_HEADERS.join(", "),
+    "Access-Control-Max-Age": "86400",
+  };
+  const origin = request.headers.get("Origin");
+
+  if (env.CORS_ALLOWED_ORIGINS.includes("*")) {
+    headers["Access-Control-Allow-Origin"] = "*";
+    return headers;
+  }
+
+  if (origin && env.CORS_ALLOWED_ORIGINS.includes(origin)) {
+    headers["Access-Control-Allow-Origin"] = origin;
+    headers.Vary = "Origin";
+  }
+
+  return headers;
+}
+
+export function jsonResponse(request, payload, status = 200, headers = {}) {
+  return new Response(JSON.stringify(payload), {
+    status,
+    headers: {
+      "Content-Type": "application/json",
+      ...buildCorsHeaders(request),
+      ...headers,
+    },
+  });
+}
+
+export function getRequestId(request) {
+  return request.headers.get("cf-ray") || crypto.randomUUID();
+}
+
+export function buildSearchResponseHeaders({ requestId, durationMs, meta }) {
+  const headers = {
+    "X-Search-Request-Id": requestId,
+    "X-Search-Duration-Ms": String(durationMs),
+    "X-Search-Cache": meta.cache_status,
+    "X-Search-Cache-Layer": meta.cache_layer || "none",
+    "X-Search-Fallback-Path": meta.fallback_path.join(","),
+    "X-Search-Strategy": meta.strategy || "tiered",
+  };
+
+  if (meta.fallback_order.length > 0) {
+    headers["X-Search-Fallback-Order"] = meta.fallback_order.join(",");
+  }
+
+  if (meta.engine_timings.length > 0) {
+    headers["Server-Timing"] = buildServerTimingHeader(meta.engine_timings);
+    const tierSummary = buildTierSummary(meta.engine_timings);
+    if (tierSummary) {
+      headers["X-Search-Upstream-Tiers"] = tierSummary;
+    }
+  }
+
+  return headers;
+}
+
+export function createOptionsResponse(request, requestId) {
+  return new Response(null, {
+    status: 204,
+    headers: {
+      ...buildCorsHeaders(request),
+      "X-Search-Request-Id": requestId,
+    },
+  });
+}
+
+export function createErrorResponse(request, requestId, error) {
+  const normalized = normalizeError(error);
+  const status = normalized.status || 500;
+  const headers = {
+    "X-Search-Request-Id": requestId,
+  };
+
+  if (normalized.details?.retry_after) {
+    headers["Retry-After"] = String(normalized.details.retry_after);
+  }
+
+  return jsonResponse(request, toErrorPayload(normalized), status, headers);
+}

package/src/platform/http.js

@@ -0,0 +1 @@
+export * from "./http.impl.js";

package/src/platform/logger.impl.js

@@ -0,0 +1,51 @@
+function pruneUndefined(value) {
+  if (!value || typeof value !== "object") {
+    return value;
+  }
+
+  const result = {};
+  for (const [key, entry] of Object.entries(value)) {
+    if (entry !== undefined) {
+      result[key] = entry;
+    }
+  }
+
+  return result;
+}
+
+function write(level, event, fields = {}, error, runtimeContext) {
+  const request = runtimeContext?.request;
+  const url = request ? new URL(request.url) : null;
+  const payload = pruneUndefined({
+    level,
+    event,
+    request_id: request?.headers?.get("cf-ray") || fields.request_id,
+    method: request?.method,
+    path: url?.pathname,
+    ...fields,
+  });
+
+  if (level === "error") {
+    console.error(JSON.stringify(payload), error || "");
+    return;
+  }
+
+  if (level === "warn") {
+    console.warn(JSON.stringify(payload), error || "");
+    return;
+  }
+
+  console.log(JSON.stringify(payload), error || "");
+}
+
+export function logInfo(event, fields = {}, runtimeContext) {
+  write("info", event, fields, undefined, runtimeContext);
+}
+
+export function logWarn(event, fields = {}, error, runtimeContext) {
+  write("warn", event, fields, error, runtimeContext);
+}
+
+export function logError(event, fields = {}, error, runtimeContext) {
+  write("error", event, fields, error, runtimeContext);
+}

package/src/platform/logger.js

@@ -0,0 +1 @@
+export * from "./logger.impl.js";

package/src/platform/metrics.impl.js

@@ -0,0 +1,43 @@
+function getStore(runtimeContext) {
+  if (!runtimeContext) {
+    return null;
+  }
+
+  if (!runtimeContext.metrics) {
+    runtimeContext.metrics = {
+      counters: [],
+      timings: [],
+    };
+  }
+
+  return runtimeContext.metrics;
+}
+
+export function recordMetric(runtimeContext, name, fields = {}) {
+  const store = getStore(runtimeContext);
+  if (!store) {
+    return;
+  }
+
+  store.counters.push({
+    name,
+    ...fields,
+  });
+}
+
+export function recordTiming(runtimeContext, name, durationMs, fields = {}) {
+  const store = getStore(runtimeContext);
+  if (!store) {
+    return;
+  }
+
+  store.timings.push({
+    name,
+    duration_ms: durationMs,
+    ...fields,
+  });
+}
+
+export function readRecordedMetrics(runtimeContext) {
+  return runtimeContext?.metrics || { counters: [], timings: [] };
+}

package/src/platform/metrics.js

@@ -0,0 +1 @@
+export * from "./metrics.impl.js";