Fix freebuff VPN block messaging

Author: jahooma

cli/src/components/waiting-room-screen.tsx

@@ -263,7 +263,23 @@ export const WaitingRoomScreen: React.FC<WaitingRoomScreenProps> = ({
                 ⚠ Free mode isn't available in your region
               </text>
               <text style={{ fg: theme.muted, wrapMode: 'word' }}>
-                {session.countryCode === 'UNKNOWN' ? (
+                {session.countryBlockReason === 'anonymous_network' ? (
+                  <>
+                    We detected VPN, Tor, proxy, relay, or anonymized network
+                    traffic
+                    {session.countryCode === 'UNKNOWN' ? (
+                      ''
+                    ) : (
+                      <>
+                        {' '}
+                        from{' '}
+                        <span fg={theme.foreground}>{session.countryCode}</span>
+                      </>
+                    )}
+                    . Freebuff can't be used from anonymized networks. Press
+                    Ctrl+C to exit.
+                  </>
+                ) : session.countryCode === 'UNKNOWN' ? (
                   <>
                     We couldn't verify an eligible location for this request.
                     VPN, Tor, proxy, or unknown-location traffic can't use

cli/src/hooks/helpers/send-message.ts

@@ -12,7 +12,7 @@ import { IS_FREEBUFF } from '../../utils/constants'
 import { processBashContext } from '../../utils/bash-context-processor'
 import { markRunningAgentsAsCancelled } from '../../utils/block-operations'
 import {
-  getCountryCodeFromFreeModeError,
+  getCountryBlockFromFreeModeError,
   getFreebuffGateErrorKind,
   isOutOfCreditsError,
   isFreeModeUnavailableError,
@@ -394,7 +394,9 @@ export const handleRunCompletion = (params: {
       updater.setError(FREE_MODE_UNAVAILABLE_MESSAGE)
       if (IS_FREEBUFF) {
         markFreebuffSessionCountryBlocked(
-          getCountryCodeFromFreeModeError(output) ?? 'UNKNOWN',
+          getCountryBlockFromFreeModeError(output) ?? {
+            countryCode: 'UNKNOWN',
+          },
         )
       }
       finalizeAfterError()
@@ -494,7 +496,9 @@ export const handleRunError = (params: {
     updater.setError(FREE_MODE_UNAVAILABLE_MESSAGE)
     if (IS_FREEBUFF) {
       markFreebuffSessionCountryBlocked(
-        getCountryCodeFromFreeModeError(error) ?? 'UNKNOWN',
+        getCountryBlockFromFreeModeError(error) ?? {
+          countryCode: 'UNKNOWN',
+        },
       )
     }
     return

cli/src/hooks/use-freebuff-session.ts

@@ -16,6 +16,10 @@ import { logger } from '../utils/logger'
 import { saveFreebuffModelPreference } from '../utils/settings'
 
 import type { FreebuffSessionResponse } from '../types/freebuff-session'
+import type {
+  FreebuffCountryBlockReason,
+  FreebuffIpPrivacySignal,
+} from '@codebuff/common/types/freebuff-session'
 
 const POLL_INTERVAL_QUEUED_MS = 5_000
 const POLL_INTERVAL_ACTIVE_MS = 30_000
@@ -319,10 +323,30 @@ export function markFreebuffSessionSuperseded(): void {
  *  Transitioning the session state here unmounts the Chat surface in favor of
  *  the waiting-room's country_blocked message, so the user can't keep typing
  *  and sending doomed requests. */
-export function markFreebuffSessionCountryBlocked(countryCode: string): void {
+export function markFreebuffSessionCountryBlocked(
+  params:
+    | string
+    | {
+        countryCode: string
+        countryBlockReason?: string
+        ipPrivacySignals?: string[]
+      },
+): void {
   if (!IS_FREEBUFF) return
+  const next =
+    typeof params === 'string'
+      ? { countryCode: params }
+      : {
+          countryCode: params.countryCode,
+          countryBlockReason: params.countryBlockReason as
+            | FreebuffCountryBlockReason
+            | undefined,
+          ipPrivacySignals: params.ipPrivacySignals as
+            | FreebuffIpPrivacySignal[]
+            | undefined,
+        }
   controller?.abort()
-  controller?.apply({ status: 'country_blocked', countryCode })
+  controller?.apply({ status: 'country_blocked', ...next })
   // Best-effort DELETE so we don't hold a waiting-room seat on a session the
   // server is already refusing to serve at chat time.
   releaseFreebuffSlot().catch(() => {})

cli/src/utils/error-handling.ts

@@ -73,6 +73,32 @@ export const getCountryCodeFromFreeModeError = (
     : null
 }
 
+export const getCountryBlockFromFreeModeError = (
+  error: unknown,
+): {
+  countryCode: string
+  countryBlockReason?: string
+  ipPrivacySignals?: string[]
+} | null => {
+  if (!isFreeModeUnavailableError(error)) return null
+  const countryCode = getCountryCodeFromFreeModeError(error) ?? 'UNKNOWN'
+  const countryBlockReason = (error as { countryBlockReason?: unknown })
+    .countryBlockReason
+  const ipPrivacySignals = (error as { ipPrivacySignals?: unknown })
+    .ipPrivacySignals
+
+  return {
+    countryCode,
+    countryBlockReason:
+      typeof countryBlockReason === 'string' ? countryBlockReason : undefined,
+    ipPrivacySignals: Array.isArray(ipPrivacySignals)
+      ? ipPrivacySignals.filter(
+          (signal): signal is string => typeof signal === 'string',
+        )
+      : undefined,
+  }
+}
+
 /**
  * Freebuff waiting-room gate errors returned by /api/v1/chat/completions.
  *

common/src/types/freebuff-session.ts

@@ -21,6 +21,23 @@ export interface FreebuffSessionRateLimit {
   recentCount: number
 }
 
+export type FreebuffCountryBlockReason =
+  | 'country_not_allowed'
+  | 'anonymized_or_unknown_country'
+  | 'anonymous_network'
+  | 'missing_client_ip'
+  | 'unresolved_client_ip'
+
+export type FreebuffIpPrivacySignal =
+  | 'anonymous'
+  | 'vpn'
+  | 'proxy'
+  | 'tor'
+  | 'relay'
+  | 'res_proxy'
+  | 'hosting'
+  | 'service'
+
 export type FreebuffSessionServerResponse =
   | {
       /** Waiting room is globally off; free-mode requests flow through
@@ -106,6 +123,8 @@ export type FreebuffSessionServerResponse =
        *  screen. `countryCode` is the resolved country, or UNKNOWN. */
       status: 'country_blocked'
       countryCode: string
+      countryBlockReason?: FreebuffCountryBlockReason
+      ipPrivacySignals?: FreebuffIpPrivacySignal[]
     }
   | {
       /** User has an active session bound to a different model. Returned

web/src/app/api/v1/chat/completions/__tests__/completions.test.ts

@@ -593,6 +593,7 @@ describe('/api/v1/chat/completions POST endpoint', () => {
       const body = await response.json()
       expect(body.error).toBe('free_mode_unavailable')
       expect(body.countryCode).toBe('UNKNOWN')
+      expect(body.countryBlockReason).toBe('missing_client_ip')
     })
 
     it('rejects free-mode requests from anonymized Cloudflare country codes', async () => {
@@ -634,6 +635,7 @@ describe('/api/v1/chat/completions POST endpoint', () => {
       const body = await response.json()
       expect(body.error).toBe('free_mode_unavailable')
       expect(body.countryCode).toBe('UNKNOWN')
+      expect(body.countryBlockReason).toBe('anonymized_or_unknown_country')
     })
 
     it('lets freebuff use GLM 5.1 through Fireworks availability rules', async () => {

web/src/app/api/v1/chat/completions/_post.ts

@@ -292,6 +292,8 @@ export async function postChatCompletions(params: {
             error: 'free_mode_unavailable',
             message: 'Free mode is not available in your country.',
             countryCode: countryAccess.countryCode ?? 'UNKNOWN',
+            countryBlockReason: countryAccess.blockReason,
+            ipPrivacySignals: countryAccess.ipPrivacy?.signals,
           },
           { status: 403 },
         )

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

@@ -165,6 +165,7 @@ describe('POST /api/v1/freebuff/session', () => {
     const body = await resp.json()
     expect(body.status).toBe('country_blocked')
     expect(body.countryCode).toBe('FR')
+    expect(body.countryBlockReason).toBe('country_not_allowed')
     expect(sessionDeps.rows.size).toBe(0)
   })
 
@@ -178,6 +179,7 @@ describe('POST /api/v1/freebuff/session', () => {
     const body = await resp.json()
     expect(body.status).toBe('country_blocked')
     expect(body.countryCode).toBe('UNKNOWN')
+    expect(body.countryBlockReason).toBe('missing_client_ip')
     expect(sessionDeps.rows.size).toBe(0)
   })
 
@@ -191,6 +193,7 @@ describe('POST /api/v1/freebuff/session', () => {
     const body = await resp.json()
     expect(body.status).toBe('country_blocked')
     expect(body.countryCode).toBe('UNKNOWN')
+    expect(body.countryBlockReason).toBe('anonymized_or_unknown_country')
     expect(sessionDeps.rows.size).toBe(0)
   })
 
@@ -256,6 +259,7 @@ describe('GET /api/v1/freebuff/session', () => {
     const body = await resp.json()
     expect(body.status).toBe('country_blocked')
     expect(body.countryCode).toBe('FR')
+    expect(body.countryBlockReason).toBe('country_not_allowed')
   })
 
   test('returns banned 403 on GET for banned user', async () => {

web/src/app/api/v1/freebuff/session/_handlers.ts

@@ -34,6 +34,8 @@ async function countryBlockedResponse(
     {
       status: 'country_blocked',
       countryCode: countryAccess.countryCode ?? 'UNKNOWN',
+      countryBlockReason: countryAccess.blockReason,
+      ipPrivacySignals: countryAccess.ipPrivacy?.signals,
     },
     { status: 403 },
   )

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

@@ -124,6 +124,24 @@ describe('free mode country access', () => {
     expect(access.ipPrivacy?.signals).toEqual(['res_proxy'])
   })
 
+  test('allows allowlisted countries when IPinfo only reports hosting or service', async () => {
+    const access = await getFreeModeCountryAccess(
+      makeReq({
+        'cf-ipcountry': 'US',
+        'x-forwarded-for': '203.0.113.10',
+      }),
+      {
+        ipinfoToken: 'test-token',
+        lookupIpPrivacy: async () => ({
+          signals: ['hosting', 'service'],
+        }),
+      },
+    )
+    expect(access.allowed).toBe(true)
+    expect(access.blockReason).toBe(null)
+    expect(access.ipPrivacy?.signals).toEqual(['hosting', 'service'])
+  })
+
   test('allows allowlisted countries when privacy lookup finds no anonymous signals', async () => {
     const access = await getFreeModeCountryAccess(
       makeReq({
@@ -204,4 +222,22 @@ describe('free mode country access', () => {
       signals: ['anonymous'],
     })
   })
+
+  test('treats is_anonymous as blocking even when service is present', async () => {
+    const fetch = async () =>
+      Response.json({
+        service: 'Privacy Provider',
+        is_anonymous: true,
+      })
+
+    const privacy = await lookupIpinfoPrivacy({
+      ip: '198.51.100.44',
+      token: 'test-token',
+      fetch: fetch as unknown as typeof globalThis.fetch,
+    })
+
+    expect(privacy).toEqual({
+      signals: ['service', 'anonymous'],
+    })
+  })
 })