Require Scamalytics for residential proxy blocks

Author: jahooma

docs/environment-variables.md

@@ -7,7 +7,7 @@
 - Runtime/OS env: pass typed snapshots instead of reading `process.env` throughout the codebase.
 - `IPINFO_TOKEN` is required; free-mode country gating uses it to check IPinfo privacy signals for VPN/proxy/Tor/relay/hosting traffic.
 - `SPUR_TOKEN` is required; VPN/proxy/Tor/residential-proxy privacy signals use Spur Context API corroboration.
-- `SCAMALYTICS_API_KEY` is required; when IPinfo reports privacy or hosting/service signals, free-mode gating also checks Scamalytics for a fraud score and proxy/Tor/VPN evidence. In allowlisted countries, full access requires both Spur and Scamalytics to return clean follow-up results. Provider failures, ambiguous results, VPN/proxy/residential-proxy signals, and hosting/datacenter signals fall back to limited access. Only Cloudflare Tor or Tor corroborated by another provider is blocked entirely by the IP-intelligence gate.
+- `SCAMALYTICS_API_KEY` is required; when IPinfo reports privacy or hosting/service signals, free-mode gating also checks Scamalytics for a fraud score and proxy/Tor/VPN evidence. In allowlisted countries, full access requires both Spur and Scamalytics to return clean follow-up results. Provider failures, ambiguous results, VPN/generic-proxy signals, and hosting/datacenter signals fall back to limited access. Residential proxy is blocked only when Scamalytics also reports residential/proxy evidence or a medium+ fraud score, as are Cloudflare Tor or Tor corroborated by another provider.
 - `CODEBUFF_FULL_TELEMETRY=true` or `CODEBUFF_FULL_TELEMETRY_IDS=user-id,email@example.com`
   disables client analytics sampling for targeted debugging. Use sparingly because it can send full CLI log payloads.
 

docs/freebuff-waiting-room.md

@@ -181,7 +181,7 @@ All endpoints authenticate via the standard `Authorization: Bearer <api-key>` or
 - Existing active+unexpired row, **different model** → reject with `model_locked` (HTTP 409); `active_instance_id` is **not** rotated so the other CLI stays valid. Client must DELETE the session before switching.
 - Existing active+expired row → reset to queued with fresh `queued_at` and the requested `model` (re-queue at back).
 
-Before any of those state transitions, the handler requires a resolved country and IPinfo privacy classification. Unsupported countries enter limited Freebuff access. In allowlisted countries, IPinfo privacy/hosting/service signals trigger paid follow-up checks with Spur and Scamalytics. Full access is restored only when both follow-up providers return clean context; suspicious or failed follow-up checks fall back to limited access. The server records a 0-100 privacy risk score for observability/cache rows; named/recent IPinfo anonymizer observations raise that score, while generic Scamalytics third-party proxy labels do not override a low top-level Scamalytics score by themselves. VPN, proxy, residential proxy, and hosting/datacenter signals limit access by default; only Cloudflare Tor country detection or Tor corroborated by another provider is hard-blocked by the IP-intelligence gate.
+Before any of those state transitions, the handler requires a resolved country and IPinfo privacy classification. Unsupported countries enter limited Freebuff access. In allowlisted countries, IPinfo privacy/hosting/service signals trigger paid follow-up checks with Spur and Scamalytics. Full access is restored when both follow-up providers return clean context; suspicious or failed follow-up checks fall back to limited access. The server records a 0-100 privacy risk score for observability/cache rows; named/recent IPinfo anonymizer observations raise that score, while generic Scamalytics third-party proxy labels do not override a low top-level Scamalytics score by themselves. VPN, generic proxy, and hosting/datacenter signals limit access when follow-up providers do not clear them. Residential proxy signals hard-block only when Scamalytics also reports residential/proxy evidence or a medium+ fraud score. Cloudflare Tor country detection or Tor corroborated by another provider is also hard-blocked by the IP-intelligence gate.
 
 Response shapes:
 

web/src/app/api/v1/freebuff/session/__tests__/session.test.ts

@@ -506,8 +506,8 @@ describe('GET /api/v1/freebuff/session', () => {
           blockReason: 'anonymous_network',
           cfCountry: 'US',
           geoipCountry: null,
-          ipPrivacy: { signals: ['res_proxy'] },
-          spurIpPrivacy: { signals: ['res_proxy'] },
+          ipPrivacy: { signals: ['vpn'] },
+          spurIpPrivacy: { signals: ['proxy'] },
           spurStatus: 'suspicious',
           ...NOT_CHECKED_SCAMALYTICS_CONTEXT,
           hasClientIp: true,
@@ -520,7 +520,7 @@ describe('GET /api/v1/freebuff/session', () => {
     expect(body.status).toBe('none')
     expect(body.accessTier).toBe('limited')
     expect(body.countryBlockReason).toBe('anonymous_network')
-    expect(body.ipPrivacySignals).toEqual(['res_proxy'])
+    expect(body.ipPrivacySignals).toEqual(['vpn'])
     expect(sessionDeps.rows.size).toBe(0)
   })
 

web/src/server/__tests__/free-mode-country.test.ts

@@ -184,7 +184,7 @@ describe('free mode country access', () => {
     expect(getFreeModePrivacyProviderDecision(access)).toBe('ipinfo_only')
   })
 
-  test('allows allowlisted countries when Spur does not corroborate IPinfo residential proxy detection', async () => {
+  test('allows allowlisted countries when follow-up providers clear IPinfo residential proxy detection', async () => {
     const access = await getFreeModeCountryAccess(
       makeReq({
         'cf-ipcountry': 'US',
@@ -211,6 +211,8 @@ describe('free mode country access', () => {
     expect(access.ipPrivacy?.signals).toEqual(['res_proxy'])
     expect(access.spurIpPrivacy?.signals).toEqual([])
     expect(access.spurStatus).toBe('clean')
+    expect(getFreeModeRiskScore(access)).toBe(70)
+    expect(shouldHardBlockFreeModeAccess(access)).toBe(false)
   })
 
   test('allows allowlisted countries when Spur does not corroborate IPinfo hosting or service detection', async () => {
@@ -382,6 +384,65 @@ describe('free mode country access', () => {
     expect(shouldHardBlockFreeModeAccess(access)).toBe(true)
   })
 
+  test('hard-blocks residential proxy when Scamalytics also corroborates it', async () => {
+    const access = await getFreeModeCountryAccess(
+      makeReq({
+        'cf-ipcountry': 'US',
+        'x-forwarded-for': '203.0.113.10',
+      }),
+      {
+        ipinfoToken: 'test-token',
+        spurToken: 'test-spur-token',
+        lookupIpPrivacy: async () => ({
+          signals: ['res_proxy'],
+        }),
+        lookupSpurIpPrivacy: async () => ({
+          signals: ['proxy'],
+        }),
+        lookupScamalyticsIpRisk: async () => ({
+          signals: [],
+          score: 60,
+          risk: 'medium',
+        }),
+      },
+    )
+
+    expect(access.allowed).toBe(false)
+    expect(access.blockReason).toBe('anonymous_network')
+    expect(getFreeModeRiskScore(access)).toBe(95)
+    expect(getFreeModePrivacyDecision(access)).toBe('corroborated_block')
+    expect(shouldHardBlockFreeModeAccess(access)).toBe(true)
+  })
+
+  test('keeps IPinfo and Spur residential proxy corroboration limited when Scamalytics is clean', async () => {
+    const access = await getFreeModeCountryAccess(
+      makeReq({
+        'cf-ipcountry': 'US',
+        'x-forwarded-for': '203.0.113.10',
+      }),
+      {
+        ipinfoToken: 'test-token',
+        spurToken: 'test-spur-token',
+        lookupIpPrivacy: async () => ({
+          signals: ['res_proxy'],
+        }),
+        lookupSpurIpPrivacy: async () => ({
+          signals: ['proxy'],
+        }),
+        lookupScamalyticsIpRisk: async () => ({
+          signals: [],
+          score: 20,
+          risk: 'low',
+        }),
+      },
+    )
+
+    expect(access.allowed).toBe(false)
+    expect(access.blockReason).toBe('anonymous_network')
+    expect(getFreeModeRiskScore(access)).toBe(75)
+    expect(shouldHardBlockFreeModeAccess(access)).toBe(false)
+  })
+
   test('keeps IPinfo VPN/proxy detections in limited mode when Spur lookup fails', async () => {
     const access = await getFreeModeCountryAccess(
       makeReq({

web/src/server/free-mode-country.ts

@@ -172,6 +172,12 @@ function hasTorPrivacySignal(
   return ipPrivacy?.signals.includes('tor') ?? false
 }
 
+function hasResidentialProxySignal(
+  ipPrivacy: FreeModeIpPrivacy | null | undefined,
+): boolean {
+  return ipPrivacy?.signals.includes('res_proxy') ?? false
+}
+
 function hasCorroboratedTorSignal(
   countryAccess: Partial<
     Pick<
@@ -187,6 +193,40 @@ function hasCorroboratedTorSignal(
   )
 }
 
+function hasCorroboratedResidentialProxySignal(
+  countryAccess: Partial<
+    Pick<
+      FreeModeCountryAccess,
+      | 'ipPrivacy'
+      | 'spurIpPrivacy'
+      | 'scamalyticsIpPrivacy'
+      | 'scamalyticsScore'
+    >
+  >,
+): boolean {
+  const ipinfoResidentialProxy = hasResidentialProxySignal(
+    countryAccess.ipPrivacy,
+  )
+  const spurResidentialProxy = hasResidentialProxySignal(
+    countryAccess.spurIpPrivacy,
+  )
+  const scamalyticsResidentialProxy = hasResidentialProxySignal(
+    countryAccess.scamalyticsIpPrivacy,
+  )
+  const scamalyticsCorroborates =
+    scamalyticsResidentialProxy ||
+    hasHardBlockedPrivacySignal(countryAccess.scamalyticsIpPrivacy) ||
+    (countryAccess.scamalyticsScore ?? 0) >= SCAMALYTICS_LIMITED_RISK_SCORE
+
+  return (
+    (ipinfoResidentialProxy && scamalyticsCorroborates) ||
+    (spurResidentialProxy && scamalyticsCorroborates) ||
+    (scamalyticsResidentialProxy &&
+      (hasHardBlockedPrivacySignal(countryAccess.ipPrivacy) ||
+        hasHardBlockedPrivacySignal(countryAccess.spurIpPrivacy)))
+  )
+}
+
 function maxPrivacySignalRisk(
   ipPrivacy: FreeModeIpPrivacy | null | undefined,
 ): number {
@@ -280,6 +320,9 @@ export function getFreeModeRiskScore(
   if (hasCorroboratedTorSignal(countryAccess)) {
     score = Math.max(score, 95)
   }
+  if (hasCorroboratedResidentialProxySignal(countryAccess)) {
+    score = Math.max(score, 95)
+  }
 
   return Math.min(100, Math.max(0, Math.round(score)))
 }
@@ -299,7 +342,10 @@ export function shouldHardBlockFreeModeAccess(
 ): boolean {
   if (countryAccess.cfCountry === CLOUDFLARE_TOR_COUNTRY) return true
   if (countryAccess.blockReason !== 'anonymous_network') return false
-  return hasCorroboratedTorSignal(countryAccess)
+  return (
+    hasCorroboratedTorSignal(countryAccess) ||
+    hasCorroboratedResidentialProxySignal(countryAccess)
+  )
 }
 
 export function getFreeModePrivacyDecision(