litescrape-mcp-server 0.2.0 → 0.2.1

package/README.md

@@ -141,7 +141,7 @@ Requests time out after 120 seconds by default (the API's own deadline is 90 sec
 
 `litescrape-mcp-server --http` (or `LITESCRAPE_MCP_TRANSPORT=http`) serves MCP over HTTP instead of stdio: stateless `POST /mcp`, `GET /healthz`, listening on `PORT` (default 8080) and `HOST` (default `0.0.0.0`), or `--port` and `--host`. Each request's API key comes from its `Authorization: Bearer` header or `?api_key=` query parameter, so one process serves keyed and keyless callers; `LITESCRAPE_API_KEY` is ignored in this mode. This is what runs at `https://mcp.litescrape.com/mcp`.
 
-Behind a shared address, keyless callers would all count against one allowance. `LITESCRAPE_KEYLESS_PROXY_SECRET` is the secret the Litescrape API shares with its own hosted endpoint for forwarding each caller's address; it is not needed for a private deployment, where the server's own address is metered.
+Behind a shared address, keyless callers would all count against one allowance. `LITESCRAPE_KEYLESS_PROXY_SECRET` is the secret the Litescrape API shares with its own hosted endpoint for forwarding each caller's address, and `LITESCRAPE_EDGE_SECRET` is the value Cloudflare adds in front of that endpoint so the caller can be read from `CF-Connecting-IP`. Neither is needed for a private deployment, where the server's own address is metered.
 
 ```
 docker build -t litescrape-mcp-server . && docker run -p 8080:8080 litescrape-mcp-server --http

package/dist/http.d.ts

@@ -4,6 +4,8 @@ export declare const MCP_PATH = "/mcp";
 export declare const HEALTH_PATH = "/healthz";
 export declare const FORWARDED_IP_HEADER = "X-Litescrape-Keyless-Ip";
 export declare const PROXY_SECRET_HEADER = "X-Litescrape-Keyless-Secret";
+export declare const EDGE_SECRET_HEADER = "x-litescrape-edge-secret";
+export declare const EDGE_CLIENT_HEADER = "cf-connecting-ip";
 export interface HttpOptions {
     /**
      * Secret shared with the Litescrape API. When set, every upstream request
@@ -11,6 +13,12 @@ export interface HttpOptions {
      * caller rather than to this server's own address.
      */
     proxySecret?: string;
+    /**
+     * Secret Cloudflare adds to every request it relays. When set, the caller is
+     * read from CF-Connecting-IP on requests that carry it, and nothing is
+     * forwarded for requests that bypassed Cloudflare.
+     */
+    edgeSecret?: string;
     apiUrl?: string;
     timeoutMs?: number;
     fetch?: ClientOptions['fetch'];
@@ -19,11 +27,14 @@ export interface HttpOptions {
 }
 export declare function bearerToken(req: IncomingMessage): string | undefined;
 /**
- * The caller as the ingress reports it. X-Forwarded-For is passed through
- * unchanged: the API meters it only when it holds exactly one address, so a
- * crafted multi-hop value is refused there instead of being trusted here.
+ * The caller as the ingress reports it. With an edge secret configured, only a
+ * request carrying it is known to have come through Cloudflare, and its caller
+ * is CF-Connecting-IP; a request that bypassed Cloudflare gets no caller at all.
+ * Without one, X-Forwarded-For is passed through unchanged: the API meters it
+ * only when it holds exactly one address, so a crafted multi-hop value is
+ * refused there instead of being trusted here.
  */
-export declare function callerAddress(req: IncomingMessage): string | undefined;
+export declare function callerAddress(req: IncomingMessage, options?: Pick<HttpOptions, 'edgeSecret'>): string | undefined;
 export declare function clientForRequest(req: IncomingMessage, options: HttpOptions): LitescrapeClient;
 export declare function handleRequest(req: IncomingMessage, res: ServerResponse, options: HttpOptions): Promise<void>;
 export declare function createHttpServer(options?: HttpOptions): Server;

package/dist/http.js

@@ -1,3 +1,4 @@
+import { createHash, timingSafeEqual } from 'node:crypto';
 import { createServer as createNodeServer, } from 'node:http';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { LitescrapeClient } from './client.js';
@@ -9,6 +10,12 @@ export const HEALTH_PATH = '/healthz';
 // shared secret, and only when it holds exactly one address.
 export const FORWARDED_IP_HEADER = 'X-Litescrape-Keyless-Ip';
 export const PROXY_SECRET_HEADER = 'X-Litescrape-Keyless-Secret';
+// Behind Cloudflare the socket peer is one of its egress addresses and
+// X-Forwarded-For is a chain, so the caller is CF-Connecting-IP; a transform
+// rule on the zone adds the edge secret, which is how a request proves it came
+// through Cloudflare rather than straight to the origin with forged headers.
+export const EDGE_SECRET_HEADER = 'x-litescrape-edge-secret';
+export const EDGE_CLIENT_HEADER = 'cf-connecting-ip';
 function requestUrl(req) {
     return new URL(req.url ?? '/', 'http://localhost');
 }
@@ -20,21 +27,37 @@ export function bearerToken(req) {
     const fromQuery = requestUrl(req).searchParams.get('api_key')?.trim();
     return fromQuery || undefined;
 }
+function headerValue(req, name) {
+    const raw = req.headers[name];
+    return (Array.isArray(raw) ? raw.join(', ') : raw)?.trim() ?? '';
+}
+function sameSecret(presented, expected) {
+    const digest = (value) => createHash('sha256').update(value).digest();
+    return timingSafeEqual(digest(presented), digest(expected));
+}
 /**
- * The caller as the ingress reports it. X-Forwarded-For is passed through
- * unchanged: the API meters it only when it holds exactly one address, so a
- * crafted multi-hop value is refused there instead of being trusted here.
+ * The caller as the ingress reports it. With an edge secret configured, only a
+ * request carrying it is known to have come through Cloudflare, and its caller
+ * is CF-Connecting-IP; a request that bypassed Cloudflare gets no caller at all.
+ * Without one, X-Forwarded-For is passed through unchanged: the API meters it
+ * only when it holds exactly one address, so a crafted multi-hop value is
+ * refused there instead of being trusted here.
  */
-export function callerAddress(req) {
-    const forwarded = req.headers['x-forwarded-for'];
-    const value = (Array.isArray(forwarded) ? forwarded.join(', ') : forwarded)?.trim();
-    if (value)
-        return value;
+export function callerAddress(req, options = {}) {
+    if (options.edgeSecret) {
+        const presented = headerValue(req, EDGE_SECRET_HEADER);
+        if (!presented || !sameSecret(presented, options.edgeSecret))
+            return undefined;
+        return headerValue(req, EDGE_CLIENT_HEADER) || undefined;
+    }
+    const forwarded = headerValue(req, 'x-forwarded-for');
+    if (forwarded)
+        return forwarded;
     return req.socket?.remoteAddress || undefined;
 }
 export function clientForRequest(req, options) {
     const headers = {};
-    const caller = options.proxySecret ? callerAddress(req) : undefined;
+    const caller = options.proxySecret ? callerAddress(req, options) : undefined;
     if (options.proxySecret && caller) {
         headers[FORWARDED_IP_HEADER] = caller;
         headers[PROXY_SECRET_HEADER] = options.proxySecret;

package/dist/index.js

@@ -19,12 +19,20 @@ function http(args) {
     const port = Number(flag(args, '--port') ?? process.env.PORT ?? 8080);
     const host = flag(args, '--host') ?? process.env.HOST ?? '0.0.0.0';
     const proxySecret = process.env.LITESCRAPE_KEYLESS_PROXY_SECRET?.trim() || undefined;
+    const edgeSecret = process.env.LITESCRAPE_EDGE_SECRET?.trim() || undefined;
     const apiUrl = process.env.LITESCRAPE_API_URL?.trim() || undefined;
     const timeoutMs = Number(process.env.LITESCRAPE_TIMEOUT_MS) || undefined;
-    const server = createHttpServer({ proxySecret, apiUrl, timeoutMs, log: console.error });
+    const server = createHttpServer({
+        proxySecret,
+        edgeSecret,
+        apiUrl,
+        timeoutMs,
+        log: console.error,
+    });
     server.listen(port, host, () => {
+        const forwarding = proxySecret ? (edgeSecret ? 'on, Cloudflare edge' : 'on') : 'off';
         console.error(`${PACKAGE_NAME} ${VERSION} listening on http://${host}:${port}${MCP_PATH} ` +
-            `(API key per request, caller forwarding ${proxySecret ? 'on' : 'off'})`);
+            `(API key per request, caller forwarding ${forwarding})`);
     });
     const stop = () => server.close(() => process.exit(0));
     process.on('SIGTERM', stop);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "litescrape-mcp-server",
-	"version": "0.2.0",
+	"version": "0.2.1",
 	"description": "MCP server for the Litescrape API: Google Search, Bing, DuckDuckGo and Google Maps free without an API key, plus Google AI Mode, AI Overview, Shopping and Reviews with one. Stdio or Streamable HTTP.",
 	"license": "MIT",
 	"homepage": "https://litescrape.com",

package/server.json

@@ -8,12 +8,12 @@
 		"source": "github"
 	},
 	"websiteUrl": "https://litescrape.com",
-	"version": "0.2.0",
+	"version": "0.2.1",
 	"packages": [
 		{
 			"registryType": "npm",
 			"identifier": "litescrape-mcp-server",
-			"version": "0.2.0",
+			"version": "0.2.1",
 			"transport": {
 				"type": "stdio"
 			},