Skip to content

Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. πŸ”₯

fix(api): negative-cache failed spur lookups and normalize keyless ip (#4400)

tomsideguide9835405b9846
diff --git a/apps/api/src/__tests__/snips/v2/research.test.ts b/apps/api/src/__tests__/snips/v2/research.test.ts
index fbcd5fdea..6815f5cab 100644
--- a/apps/api/src/__tests__/snips/v2/research.test.ts
+++ b/apps/api/src/__tests__/snips/v2/research.test.ts
@@ -66,11 +66,9 @@ function keylessHeaders(forwardedIp: string): Record<string, string> {
// blocking KEYS scan on the shared rate-limit Redis, and stays deterministic
// under concurrency: every parallel no-secret snip bumps the same client-IP
// key, so the diff below still identifies exactly one bumped candidate.
-// The server keys counters on the RAW client-IP string: only keyless
-// *eligibility* strips the ::ffff: prefix (lib/keyless.ts normalizeKeylessIpv4
-// is not applied before consumeKeylessRequest/keylessTeamId), so an
-// IPv6-mapped connection legitimately produces keys like
-// `keyless_requests:::ffff:127.0.0.1`. Cover both spellings per candidate.
+// The server normalizes ::ffff:-mapped IPs to plain IPv4 before keying
+// (lib/keyless.ts normalizeKeylessIpv4, applied in auth), but keys written by
+// older builds may still carry the raw spelling, so cover both per candidate.
function candidateKeylessIps(): string[] {
const bare = new Set<string>(["127.0.0.1"]);
for (const addrs of Object.values(os.networkInterfaces())) {
diff --git a/apps/api/src/controllers/auth.ts b/apps/api/src/controllers/auth.ts
index 780a426af..e98cda064 100644
--- a/apps/api/src/controllers/auth.ts
+++ b/apps/api/src/controllers/auth.ts
@@ -17,6 +17,7 @@ import {
keylessExhaustionTelemetry,
isKeylessIpEligible,
keylessTeamId,
+ normalizeKeylessIpv4,
} from "../lib/keyless";
import { isKeylessIpSuspicious } from "../lib/spur";
import { checkIpRestriction } from "../lib/ip-restriction";
@@ -459,6 +460,10 @@ async function handleKeylessAuth(
// usable as arbitrary limiter buckets. Anything else falls through to 401.
if (!isKeylessIpEligible(ip)) return unauthorized;
+ // Canonicalize `::ffff:`-mapped IPv4 so a client gets one Spur cache entry,
+ // one quota bucket, and one team id regardless of how the socket reported it.
+ ip = normalizeKeylessIpv4(ip);
+
// Optional Spur Context check (only when SPUR_API_KEY is set): refuse keyless
// for IPs fronting anonymizing/rotating infrastructure (VPN/proxy/TOR), the
// main way the per-IP caps get bypassed. Fails open on any Spur error, and
diff --git a/apps/api/src/lib/__tests__/spur.test.ts b/apps/api/src/lib/__tests__/spur.test.ts
index 3329f1203..005c967a4 100644
--- a/apps/api/src/lib/__tests__/spur.test.ts
+++ b/apps/api/src/lib/__tests__/spur.test.ts
@@ -13,7 +13,12 @@ vi.mock("../logger", () => ({
}));
vi.mock("../../services/rate-limiter", () => ({
- redisRateLimitClient: { get: vi.fn(), set: vi.fn(), eval: vi.fn() },
+ redisRateLimitClient: {
+ get: vi.fn(),
+ mget: vi.fn(),
+ set: vi.fn(),
+ eval: vi.fn(),
+ },
}));
// Minimal in-memory Redis backing the mock: enough SET semantics (NX guard,
@@ -23,6 +28,10 @@ function installFakeRedis(): Map<string, string> {
(redisRateLimitClient.get as Mock).mockImplementation(async (k: string) =>
store.has(k) ? store.get(k)! : null,
);
+ (redisRateLimitClient.mget as Mock).mockImplementation(
+ async (...keys: (string | string[])[]) =>
+ keys.flat().map(k => (store.has(k) ? store.get(k)! : null)),
+ );
(redisRateLimitClient.set as Mock).mockImplementation(
async (k: string, v: string, ...args: unknown[]) => {
if (args.includes("NX") && store.has(k)) return null;
@@ -63,11 +72,36 @@ describe("Spur keyless IP reputation", () => {
it("flags an IP fronting a live VPN/proxy tunnel", async () => {
mockFetch(async () =>
- okResponse({ ip: "1.2.3.4", tunnels: [{ type: "VPN" }] }),
+ okResponse({
+ ip: "1.2.3.4",
+ tunnels: [{ anonymous: true, type: "VPN" }],
+ }),
);
expect(await isKeylessIpSuspicious("1.2.3.4")).toBe(true);
});
+ it("allows a non-anonymous tunnel such as an enterprise VPN", async () => {
+ mockFetch(async () =>
+ okResponse({
+ ip: "1.2.3.14",
+ tunnels: [{ anonymous: false, operator: "ZSCALER", type: "VPN" }],
+ }),
+ );
+ expect(await isKeylessIpSuspicious("1.2.3.14")).toBe(false);
+ });
+
+ it("fails open on a malformed cached context instead of throwing", async () => {
+ store.set(
+ "spur_context:1.2.3.17",
+ JSON.stringify({ tunnels: 5, risks: "TUNNEL", client: { proxies: {} } }),
+ );
+ const fetchFn = mockFetch(async () =>
+ okResponse({ tunnels: [{ anonymous: true, type: "VPN" }] }),
+ );
+ expect(await isKeylessIpSuspicious("1.2.3.17")).toBe(false);
+ expect(fetchFn).not.toHaveBeenCalled();
+ });
+
it("allows a clean (datacenter-only) IP", async () => {
mockFetch(async () =>
okResponse({ ip: "1.2.3.5", infrastructure: "DATACENTER", risks: [] }),
@@ -119,27 +153,48 @@ describe("Spur keyless IP reputation", () => {
expect(results).toEqual([false, false, false, false, false]);
});
- it("fails open on a non-200 Spur response and caches nothing", async () => {
+ it("fails open on a non-200 Spur response and does not retry within the negative-cache window", async () => {
const fetchFn = mockFetch(async () => ({ ok: false, status: 429 }));
expect(await isKeylessIpSuspicious("1.2.3.7")).toBe(false);
+ expect(await isKeylessIpSuspicious("1.2.3.7")).toBe(false);
expect(fetchFn).toHaveBeenCalledTimes(1);
- expect(store.has("spur_context:1.2.3.7")).toBe(false);
});
- it("fails open when the Spur call throws, and releases the lock so a later call retries", async () => {
+ it("fails open when the Spur call throws, and retries once the negative cache expires", async () => {
const fetchFn = mockFetch(async () => {
throw new Error("network down");
});
expect(await isKeylessIpSuspicious("1.2.3.8")).toBe(false);
- // Lock must be freed: a subsequent call gets to fetch again.
+ expect(await isKeylessIpSuspicious("1.2.3.8")).toBe(false);
+ expect(fetchFn).toHaveBeenCalledTimes(1);
+
+ // The fake redis ignores EX; clearing it stands in for the negative TTL
+ // expiring. The lock was released, so a later call gets to fetch again.
+ store.clear();
fetchFn.mockImplementation(async () =>
- okResponse({ ip: "1.2.3.8", tunnels: [{ type: "TOR" }] }),
+ okResponse({
+ ip: "1.2.3.8",
+ tunnels: [{ anonymous: true, type: "TOR" }],
+ }),
);
expect(await isKeylessIpSuspicious("1.2.3.8")).toBe(true);
expect(fetchFn).toHaveBeenCalledTimes(2);
});
+ it("never looks up a non-IPv4 identity", async () => {
+ const fetchFn = mockFetch(async () =>
+ okResponse({ tunnels: [{ type: "VPN" }] }),
+ );
+ // Raw IPv6 and IPv4-mapped IPv6 both fail open without a Spur call: the
+ // call sites normalize `::ffff:` first, and raw IPv6 is too cheap to
+ // rotate for a per-IP cache to bound spend.
+ expect(await isKeylessIpSuspicious("2001:db8::1")).toBe(false);
+ expect(await isKeylessIpSuspicious("::ffff:1.2.3.4")).toBe(false);
+ expect(fetchFn).not.toHaveBeenCalled();
+ expect(store.size).toBe(0);
+ });
+
it("a lock loser fails open within the bound when no result ever lands", async () => {
// Pre-hold the lock under a different token so this caller can never win it,
// and never populate the cache β†’ it must give up (bounded) and fail open
diff --git a/apps/api/src/lib/keyless.ts b/apps/api/src/lib/keyless.ts
index 07c551b20..823993f02 100644
--- a/apps/api/src/lib/keyless.ts
+++ b/apps/api/src/lib/keyless.ts
@@ -43,7 +43,11 @@ const DAY_SECONDS = 86400;
// logging. Rotation intentionally creates a new cohort namespace.
export const KEYLESS_CONVERSION_COHORT_VERSION = "v1";
-function normalizeKeylessIpv4(ip: string): string {
+// Canonicalizes an IPv4-mapped IPv6 address (`::ffff:1.2.3.4`, what Node's
+// dual-stack sockets report) to plain IPv4. Every per-IP artifact (quota
+// buckets, team ids, Spur cache) must key off this form, or the same client
+// counts as two identities.
+export function normalizeKeylessIpv4(ip: string): string {
const trimmed = ip.trim();
const lower = trimmed.toLowerCase();
return lower.startsWith("::ffff:") && isIPv4(trimmed.slice(7))
@@ -329,6 +333,8 @@ export async function checkKeylessEligibility(ip: string): Promise<{
if (!ip || !isKeylessIpEligible(ip)) {
return { eligible: false, reason: "ineligible_ip" };
}
+ // Key the Spur cache and quota buckets below off the canonical IPv4 form.
+ ip = normalizeKeylessIpv4(ip);
// Optional Spur Context check (only when SPUR_API_KEY is set): treat IPs on
// anonymizing/rotating infrastructure as ineligible so the hosted MCP can
// return a bounded recovery result instead of serving a request auth rejects.
diff --git a/apps/api/src/lib/spur.ts b/apps/api/src/lib/spur.ts
index 6ee073f92..838a27839 100644
--- a/apps/api/src/lib/spur.ts
+++ b/apps/api/src/lib/spur.ts
@@ -1,288 +1,255 @@
+/**
+ * Spur Context API (https://docs.spur.us/context-api) check for the keyless
+ * free tier. When SPUR_API_KEY is set, the IPv4 behind a keyless request is
+ * looked up and IPs fronting anonymizing infrastructure (VPN/proxy/TOR
+ * tunnels, residential proxy networks) are refused keyless access.
+ *
+ * Spur bills per lookup, so an IP costs at most one upstream call per cache
+ * window regardless of outcome: results and failures are cached in Redis and
+ * concurrent callers for one IP coalesce behind a lock. Every error fails
+ * open (not suspicious) so Spur can never take down the free tier.
+ */
import { randomUUID } from "crypto";
+import { isIPv4 } from "net";
import { config } from "../config";
-import { logger } from "./logger";
import { redisRateLimitClient } from "../services/rate-limiter";
+import { logger } from "./logger";
-// Optional Spur Context API integration for the keyless free tier. When
-// SPUR_API_KEY is set, the IP behind every keyless request is looked up against
-// Spur's IP-context database (https://docs.spur.us/context-api). IPs fronting
-// anonymizing/rotating infrastructure β€” VPN/proxy/TOR tunnels or residential
-// proxy networks β€” are the cheapest way to defeat the per-IP keyless caps, so we
-// refuse keyless for them and steer the caller to sign up for an API key.
-//
-// Lookups are cached in Redis for 30 days so a given IP costs at most one Spur
-// API call per month. Concurrent misses for the same IP are collapsed with a
-// Redis single-flight lock so a burst from one IP triggers a single upstream
-// call β€” the loser callers briefly wait for that result instead of each hitting
-// Spur. The integration is entirely optional: with no key set the keyless tier
-// behaves exactly as before, and any Spur error (timeout, lock failure, outage)
-// fails open β€” the request is allowed β€” so Spur can never take down the free tier.
-
-const SPUR_API_BASE = "https://api.spur.us/v2/context";
-const CACHE_TTL_SECONDS = 30 * 24 * 60 * 60; // 30 days
-const cacheKey = (ip: string) => `spur_context:${ip}`;
-
-// Everything below is bounded so a request can never get stuck on the upstream
-// call, on holding the lock, or on waiting for another request's result.
-//
-// - FETCH_TIMEOUT_MS aborts the Spur HTTP call.
-// - LOCK_TTL_MS is the single-flight lock's auto-expiry; it sits ~1s above the
-// fetch timeout (headroom for the surrounding Redis round-trips) so the winner
-// isn't preempted mid-fetch, and it caps how long a dead winner can block
-// others (Redis expires the lock even if the process crashes before releasing).
-// - LOCK_WAIT_MS caps how long a loser waits for the winner's result before
-// failing open; POLL_INTERVAL_MS is how often it re-checks the result cache.
const FETCH_TIMEOUT_MS = 5000;
+// Headroom over the fetch timeout for the Redis round-trips around it.
const LOCK_TTL_MS = FETCH_TIMEOUT_MS + 1000;
const LOCK_WAIT_MS = LOCK_TTL_MS;
-const POLL_INTERVAL_MS = 200;
-const lockKey = (ip: string) => `spur_lock:${ip}`;
+const LOCK_POLL_MS = 200;
+const CONTEXT_TTL_SEC = 30 * 24 * 60 * 60;
+const FAILED_TTL_SEC = 10 * 60;
-const sleep = (ms: number) => new Promise(resolve => setTimeout(resolve, ms));
+const RELEASE_LOCK_SCRIPT =
+ 'if redis.call("get", KEYS[1]) == ARGV[1] then return redis.call("del", KEYS[1]) end return 0';
-// Subset of the Spur IP Context Object we read. See the API docs for the full
-// shape; everything here is optional because Spur omits empty fields.
type SpurContext = {
- ip?: string;
infrastructure?: string;
- risks?: string[];
- tunnels?: { anonymous?: boolean; operator?: string; type?: string }[];
- client?: { behaviors?: string[]; proxies?: string[] };
+ risks: string[];
+ tunnels: { anonymous?: boolean; operator?: string; type?: string }[];
+ client: { proxies: string[] };
};
-function isSpurEnabled(): boolean {
+type CacheState =
+ | { state: "hit"; ctx: SpurContext }
+ | { state: "failed" }
+ | { state: "miss" };
+
+const contextKey = (ip: string) => `spur_context:${ip}`;
+const failedKey = (ip: string) => `spur_context_failed:${ip}`;
+const lockKey = (ip: string) => `spur_lock:${ip}`;
+
+const meta = (ip: string) => ({ canonicalLog: "spur/lookup", ip });
+
+const sleep = (ms: number) => new Promise(resolve => setTimeout(resolve, ms));
+
+function summarize(ctx: SpurContext) {
+ return {
+ infrastructure: ctx.infrastructure,
+ risks: ctx.risks,
+ tunnels: ctx.tunnels.map(t => t.type),
+ proxies: ctx.client.proxies,
+ };
+}
+
+const strings = (v: unknown): string[] =>
+ Array.isArray(v) ? v.filter(x => typeof x === "string") : [];
+
+const objects = <T>(v: unknown): T[] =>
+ Array.isArray(v) ? v.filter(x => x && typeof x === "object") : [];
+
+// Both Redis and Spur feed this; the verdict code must never see an
+// unvalidated shape, since a throw here would fail the request closed.
+function toContext(raw: unknown): SpurContext | null {
+ if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+ const r = raw as Record<string, unknown>;
+ const client = r.client as Record<string, unknown> | undefined;
+ return {
+ infrastructure:
+ typeof r.infrastructure === "string" ? r.infrastructure : undefined,
+ risks: strings(r.risks),
+ tunnels: objects(r.tunnels),
+ client: { proxies: strings(client?.proxies) },
+ };
+}
+
+// Only IP-rotation infrastructure counts. DATACENTER, GEO_MISMATCH and
+// non-anonymous tunnels (enterprise VPN, ZTNA) are legit developer traffic.
+function isSuspicious(ctx: SpurContext): boolean {
return (
- typeof config.SPUR_API_KEY === "string" && config.SPUR_API_KEY.length > 0
+ ctx.tunnels.some(t => t.anonymous === true) ||
+ ctx.client.proxies.length > 0 ||
+ ctx.risks.includes("CALLBACK_PROXY") ||
+ ctx.risks.includes("TUNNEL")
);
}
-async function getCachedContext(ip: string): Promise<SpurContext | null> {
+function verdict(ip: string, ctx: SpurContext | null): boolean {
+ if (!ctx || !isSuspicious(ctx)) return false;
+ logger.info("Keyless IP flagged suspicious by Spur", {
+ ...meta(ip),
+ suspicious: true,
+ ...summarize(ctx),
+ });
+ return true;
+}
+
+// Verdict for a cache entry that is not a miss: a failure marker fails open.
+function cachedVerdict(ip: string, cached: CacheState): boolean {
+ return verdict(ip, cached.state === "hit" ? cached.ctx : null);
+}
+
+function parseContext(raw: string | null): SpurContext | null {
+ if (raw === null) return null;
try {
- const raw = await redisRateLimitClient.get(cacheKey(ip));
- return raw ? (JSON.parse(raw) as SpurContext) : null;
- } catch (error) {
- // Cache read failed (store down or corrupt value) β€” treat as a miss.
- logger.warn("Failed to read Spur context from cache", {
- canonicalLog: "spur/lookup",
- ip,
- error,
- });
+ return toContext(JSON.parse(raw));
+ } catch {
return null;
}
}
-async function cacheContext(ip: string, ctx: SpurContext): Promise<void> {
+async function readCache(ip: string): Promise<CacheState> {
+ let raw: string | null;
+ let failed: string | null;
try {
- await redisRateLimitClient.set(
- cacheKey(ip),
- JSON.stringify(ctx),
- "EX",
- CACHE_TTL_SECONDS,
+ [raw, failed] = await redisRateLimitClient.mget(
+ contextKey(ip),
+ failedKey(ip),
);
} catch (error) {
- // Best-effort: a failed cache write just means we look the IP up again.
- logger.warn("Failed to cache Spur context", {
- canonicalLog: "spur/lookup",
- ip,
- error,
- });
+ logger.warn("Spur cache read failed", { ...meta(ip), error });
+ return { state: "miss" };
}
+ const ctx = parseContext(raw);
+ if (ctx) return { state: "hit", ctx };
+ if (failed !== null) return { state: "failed" };
+ return { state: "miss" };
}
-// Compact summary of a context for logs β€” never dump the full object.
-function summarize(ctx: SpurContext) {
- return {
- infrastructure: ctx.infrastructure,
- risks: ctx.risks,
- tunnels: ctx.tunnels?.map(t => t.type),
- proxies: ctx.client?.proxies,
- };
+async function writeCache(
+ ip: string,
+ key: string,
+ value: string,
+ ttlSec: number,
+) {
+ try {
+ await redisRateLimitClient.set(key, value, "EX", ttlSec);
+ } catch (error) {
+ logger.warn("Spur cache write failed", { ...meta(ip), key, error });
+ }
}
-async function fetchContext(ip: string): Promise<SpurContext | null> {
- // Cache miss β†’ hit the real Spur API. Logged so we can track real spend.
- // The request is bounded by FETCH_TIMEOUT_MS; an abort throws and the caller
- // fails open.
- logger.info("Spur Context API request (cache miss)", {
- canonicalLog: "spur/lookup",
- ip,
- });
- const response = await fetch(`${SPUR_API_BASE}/${encodeURIComponent(ip)}`, {
- method: "GET",
- headers: { Token: config.SPUR_API_KEY! },
- signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
- });
- if (!response.ok) {
+async function releaseLock(ip: string, token: string) {
+ try {
+ await redisRateLimitClient.eval(RELEASE_LOCK_SCRIPT, 1, lockKey(ip), token);
+ } catch (error) {
+ logger.warn("Spur lock release failed", { ...meta(ip), error });
+ }
+}
+
+async function fetchContext(
+ ip: string,
+ apiKey: string,
+): Promise<SpurContext | null> {
+ logger.info("Spur Context API request (cache miss)", meta(ip));
+ const res = await fetch(
+ `https://api.spur.us/v2/context/${encodeURIComponent(ip)}`,
+ {
+ headers: { Token: apiKey },
+ signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+ },
+ );
+ if (!res.ok) {
logger.warn("Spur Context API request failed", {
- canonicalLog: "spur/lookup",
- ip,
- status: response.status,
+ ...meta(ip),
+ status: res.status,
});
return null;
}
- const ctx = (await response.json()) as SpurContext;
- logger.info("Spur Context API response", {
- canonicalLog: "spur/lookup",
- ip,
- ...summarize(ctx),
- });
+ const ctx = toContext(await res.json());
+ if (!ctx) {
+ logger.warn("Spur Context API returned a malformed body", meta(ip));
+ return null;
+ }
+ logger.info("Spur Context API response", { ...meta(ip), ...summarize(ctx) });
return ctx;
}
-// Single-flight lock: the winner (returns a token) is the only caller that hits
-// Spur for this IP; everyone else waits for its cached result. `null` means we
-// lost the race. Redis errors propagate so the caller fails open rather than
-// waiting on a lock we never held.
-async function acquireLock(ip: string): Promise<string | null> {
- const token = randomUUID();
- const result = await redisRateLimitClient.set(
- lockKey(ip),
- token,
- "PX",
- LOCK_TTL_MS,
- "NX",
- );
- return result === "OK" ? token : null;
-}
-
-// Atomic compare-and-delete so we only ever clear our own lock β€” a plain
-// get-then-del could delete a successor's lock if our lease expired in between.
-// Best-effort: failures are swallowed since the PX TTL frees the lock regardless.
-const RELEASE_LOCK_SCRIPT = `
-if redis.call("get", KEYS[1]) == ARGV[1] then
- return redis.call("del", KEYS[1])
-end
-return 0`;
-
-async function releaseLock(ip: string, token: string): Promise<void> {
+async function lookup(ip: string, apiKey: string): Promise<boolean> {
+ let ctx: SpurContext | null;
try {
- await redisRateLimitClient.eval(RELEASE_LOCK_SCRIPT, 1, lockKey(ip), token);
+ ctx = await fetchContext(ip, apiKey);
} catch (error) {
- logger.warn("Failed to release Spur single-flight lock", {
- canonicalLog: "spur/lookup",
- ip,
+ logger.warn("Spur context lookup failed; failing open", {
+ ...meta(ip),
+ timedOut: error instanceof Error && error.name === "TimeoutError",
error,
});
+ ctx = null;
+ }
+ if (ctx) {
+ await writeCache(ip, contextKey(ip), JSON.stringify(ctx), CONTEXT_TTL_SEC);
+ } else {
+ await writeCache(ip, failedKey(ip), "1", FAILED_TTL_SEC);
}
+ return verdict(ip, ctx);
}
-// Loser path: poll for the winner's cached result every POLL_INTERVAL_MS,
-// bounded by LOCK_WAIT_MS. If the result never lands (winner failed or is still
-// running at the deadline), give up and fail open.
-async function waitForResult(ip: string): Promise<SpurContext | null> {
+async function waitForResult(ip: string): Promise<boolean> {
const deadline = Date.now() + LOCK_WAIT_MS;
while (Date.now() < deadline) {
- // Clamp the last sleep to the remaining budget so we never overshoot the
- // LOCK_WAIT_MS ceiling.
- await sleep(Math.min(POLL_INTERVAL_MS, deadline - Date.now()));
- const cached = await getCachedContext(ip);
- if (cached) return cached;
+ await sleep(Math.min(LOCK_POLL_MS, deadline - Date.now()));
+ const cached = await readCache(ip);
+ if (cached.state === "miss") continue;
+ logger.info("Spur lookup coalesced by single-flight", {
+ ...meta(ip),
+ savedApiCall: true,
+ });
+ return cachedVerdict(ip, cached);
}
- return null;
+ logger.info("Spur lookup coalesced by single-flight", {
+ ...meta(ip),
+ savedApiCall: false,
+ });
+ return false;
}
-/**
- * Look up an IP's Spur context, preferring the 30-day Redis cache and only
- * caching successful (non-error) responses. Concurrent misses for the same IP
- * are collapsed via a Redis single-flight lock: one caller fetches, the rest
- * wait (bounded) for its result. Returns null when Spur is disabled or anything
- * goes wrong (lock error, timeout, upstream failure) β€” callers then fail open
- * (treat the IP as not suspicious). Every wait here is bounded, so a request can
- * never get stuck on the lock or on another request's in-flight lookup.
- */
-async function getSpurContext(ip: string): Promise<SpurContext | null> {
- if (!isSpurEnabled()) return null;
+export async function isKeylessIpSuspicious(ip: string): Promise<boolean> {
+ const apiKey = config.SPUR_API_KEY;
+ if (!apiKey || !isIPv4(ip)) return false;
- const cached = await getCachedContext(ip);
- if (cached) return cached;
+ const cached = await readCache(ip);
+ if (cached.state !== "miss") return cachedVerdict(ip, cached);
+ const token = randomUUID();
+ let locked: boolean;
try {
- const token = await acquireLock(ip);
- if (!token) {
- // Lost the race β†’ a lookup for this IP is already in flight. Wait for its
- // result instead of making our own call. Logged so we can measure how many
- // Spur calls the single-flight coalescing saves (savedApiCall === true).
- const result = await waitForResult(ip);
- logger.info("Spur lookup coalesced by single-flight", {
- canonicalLog: "spur/lookup",
- ip,
- savedApiCall: result !== null,
- });
- return result;
- }
-
- try {
- // Another winner may have populated the cache between our miss and
- // winning the lock β€” re-check before spending a Spur call.
- const fresh = await getCachedContext(ip);
- if (fresh) return fresh;
-
- const ctx = await fetchContext(ip);
- // Only cache non-error responses.
- if (ctx) await cacheContext(ip, ctx);
- return ctx;
- } finally {
- await releaseLock(ip, token);
- }
+ locked =
+ (await redisRateLimitClient.set(
+ lockKey(ip),
+ token,
+ "PX",
+ LOCK_TTL_MS,
+ "NX",
+ )) === "OK";
} catch (error) {
- // Lock error, fetch timeout/abort, or any upstream failure β†’ fail open.
- // AbortSignal.timeout rejects with a TimeoutError; flag it so the timeout
- // rate is countable separately from other failures.
- const timedOut = error instanceof Error && error.name === "TimeoutError";
logger.warn("Spur context lookup failed; failing open", {
- canonicalLog: "spur/lookup",
- ip,
- timedOut,
+ ...meta(ip),
+ timedOut: false,
error,
});
- return null;
- }
-}
-
-// Risk flags that, on their own, mark an IP as fronting proxy/tunnel
-// infrastructure. Plain DATACENTER or GEO_MISMATCH signals are intentionally
-// NOT treated as suspicious β€” many legitimate clients hit a free tier from
-// cloud/CGNAT, and the per-IP caps already cover those.
-const SUSPICIOUS_RISKS = new Set(["CALLBACK_PROXY", "TUNNEL"]);
-
-function isSuspiciousContext(ctx: SpurContext): boolean {
- // A live VPN/proxy/TOR tunnel β€” the canonical IP-rotation vector.
- if (Array.isArray(ctx.tunnels) && ctx.tunnels.length > 0) return true;
- // Residential / rotating proxy networks observed exiting this IP.
- if (Array.isArray(ctx.client?.proxies) && ctx.client.proxies.length > 0) {
- return true;
- }
- // Explicit proxy/tunnel risk flags.
- if (
- Array.isArray(ctx.risks) &&
- ctx.risks.some(r => SUSPICIOUS_RISKS.has(r))
- ) {
- return true;
+ return false;
}
- return false;
-}
+ if (!locked) return waitForResult(ip);
-/**
- * Whether the keyless tier should refuse this IP because Spur flags it as
- * anonymizing/rotating infrastructure. No-op (false) when Spur is disabled, and
- * fails open (false) on any lookup error so a Spur outage never breaks keyless.
- */
-export async function isKeylessIpSuspicious(ip: string): Promise<boolean> {
- if (!isSpurEnabled()) return false;
-
- const ctx = await getSpurContext(ip);
- if (!ctx) return false;
-
- const suspicious = isSuspiciousContext(ctx);
- if (suspicious) {
- logger.info("Keyless IP flagged suspicious by Spur", {
- canonicalLog: "spur/lookup",
- ip,
- suspicious: true,
- tunnels: ctx.tunnels?.map(t => t.type),
- proxies: ctx.client?.proxies,
- risks: ctx.risks,
- });
+ try {
+ const refreshed = await readCache(ip);
+ if (refreshed.state !== "miss") return cachedVerdict(ip, refreshed);
+ return await lookup(ip, apiKey);
+ } finally {
+ await releaseLock(ip, token);
}
- return suspicious;
}