Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. π₯
TypeScript aiai-agentsai-crawlerai-scrapingai-searchcrawlerdata-extractionhtml-to-markdownllmmarkdownscraperscrapingweb-crawlerweb-dataweb-data-extractionweb-scraperweb-scrapingweb-searchwebscraping
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.tsindex 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.tsindex 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, anddiff --git a/apps/api/src/lib/__tests__/spur.test.ts b/apps/api/src/lib/__tests__/spur.test.tsindex 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 opendiff --git a/apps/api/src/lib/keyless.ts b/apps/api/src/lib/keyless.tsindex 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.tsindex 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;}