Document Scamalytics failure fallback

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/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.
+- `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, Scamalytics outages/API errors, 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 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.
+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. A Scamalytics outage/API error is treated as a transient limited decision, not a hard block. 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/server/__tests__/free-mode-country-access-cache.test.ts

@@ -195,6 +195,42 @@ describe('free mode country access cache', () => {
     ).toBe(FREE_MODE_COUNTRY_CACHE_TRANSIENT_BLOCK_TTL_MS)
   })
 
+  test('stores transient limited decisions when Scamalytics fails after hard IPinfo signals', async () => {
+    const cacheStore: FreeModeCountryAccessCacheStore = {
+      get: mock(async () => null),
+      set: mock(async () => {}),
+    }
+
+    const access = await getCachedFreeModeCountryAccess({
+      userId,
+      req: makeReq({
+        'cf-ipcountry': 'US',
+        'cf-connecting-ip': clientIp,
+      }),
+      options: {
+        ipinfoToken: 'test-token',
+        spurToken: 'test-spur-token',
+        ipHashSecret,
+        lookupIpPrivacy: async () => ({ signals: ['vpn'] }),
+        lookupSpurIpPrivacy: async () => ({ signals: ['vpn'] }),
+        lookupScamalyticsIpRisk: async () => null,
+      },
+      cacheStore,
+      now,
+    })
+
+    expect(access.allowed).toBe(false)
+    expect(access.scamalyticsStatus).toBe('failed')
+    expect(cacheStore.set).toHaveBeenCalledWith({
+      userId,
+      access,
+      now,
+    })
+    expect(
+      expiresAtForCountryAccess(access, now).getTime() - now.getTime(),
+    ).toBe(FREE_MODE_COUNTRY_CACHE_TRANSIENT_BLOCK_TTL_MS)
+  })
+
   test('stores allowed decisions when clean Spur context clears a hard IPinfo signal', async () => {
     const cacheStore: FreeModeCountryAccessCacheStore = {
       get: mock(async () => null),

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

@@ -443,6 +443,62 @@ describe('free mode country access', () => {
     expect(shouldHardBlockFreeModeAccess(access)).toBe(false)
   })
 
+  test('keeps Scamalytics outages limited instead of hard-blocked', 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 () => {
+          throw new Error('Scamalytics unavailable')
+        },
+      },
+    )
+
+    expect(access.allowed).toBe(false)
+    expect(access.blockReason).toBe('anonymous_network')
+    expect(access.scamalyticsStatus).toBe('failed')
+    expect(getFreeModePrivacyDecision(access)).toBe(
+      'scamalytics_failed_limited',
+    )
+    expect(shouldHardBlockFreeModeAccess(access)).toBe(false)
+  })
+
+  test('treats Scamalytics API errors as limited, not blocked', 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: ['vpn'],
+        }),
+        lookupSpurIpPrivacy: async () => ({
+          signals: ['vpn'],
+        }),
+        lookupScamalyticsIpRisk: async () => null,
+      },
+    )
+
+    expect(access.allowed).toBe(false)
+    expect(access.blockReason).toBe('anonymous_network')
+    expect(access.scamalyticsStatus).toBe('failed')
+    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({