Fix freebuff VPN block messaging (#555)

Author: jahooma

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

@@ -17,6 +17,7 @@ import { exitFreebuffCleanly } from '../utils/freebuff-exit'
 import { getLogoAccentColor, getLogoBlockColor } from '../utils/theme-system'
 
 import type { FreebuffSessionResponse } from '../types/freebuff-session'
+import type { FreebuffIpPrivacySignal } from '@codebuff/common/types/freebuff-session'
 
 interface WaitingRoomScreenProps {
   session: FreebuffSessionResponse | null
@@ -55,6 +56,35 @@ const formatRetryAfter = (ms: number): string => {
   return rem === 0 ? `${hours}h` : `${hours}h ${rem}m`
 }
 
+const PRIVACY_SIGNAL_LABELS: Partial<Record<FreebuffIpPrivacySignal, string>> =
+  {
+    anonymous: 'anonymized network',
+    proxy: 'proxy',
+    relay: 'relay',
+    res_proxy: 'residential proxy',
+    tor: 'Tor',
+    vpn: 'VPN',
+  }
+
+const formatPrivacySignalList = (
+  signals: FreebuffIpPrivacySignal[] | undefined,
+): string => {
+  const labels = Array.from(
+    new Set(
+      signals
+        ?.map((signal) => PRIVACY_SIGNAL_LABELS[signal])
+        .filter((label): label is string => Boolean(label)) ?? [],
+    ),
+  )
+
+  if (labels.length === 0) {
+    return 'VPN, Tor, proxy, relay, or anonymized network'
+  }
+  if (labels.length === 1) return labels[0]
+  if (labels.length === 2) return `${labels[0]} or ${labels[1]}`
+  return `${labels.slice(0, -1).join(', ')}, or ${labels[labels.length - 1]}`
+}
+
 export const WaitingRoomScreen: React.FC<WaitingRoomScreenProps> = ({
   session,
   error,
@@ -263,7 +293,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{' '}
+                    {formatPrivacySignalList(session.ipPrivacySignals)} 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,14 @@ 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: {
+  countryCode: string
+  countryBlockReason?: FreebuffCountryBlockReason
+  ipPrivacySignals?: FreebuffIpPrivacySignal[]
+}): void {
   if (!IS_FREEBUFF) return
   controller?.abort()
-  controller?.apply({ status: 'country_blocked', countryCode })
+  controller?.apply({ status: 'country_blocked', ...params })
   // 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/__tests__/error-handling.test.ts

@@ -3,6 +3,7 @@ import { describe, test, expect } from 'bun:test'
 import {
   isOutOfCreditsError,
   isFreeModeUnavailableError,
+  getCountryBlockFromFreeModeError,
   OUT_OF_CREDITS_MESSAGE,
   FREE_MODE_UNAVAILABLE_MESSAGE,
   createErrorMessage,
@@ -70,7 +71,11 @@ describe('error-handling', () => {
 
   describe('isFreeModeUnavailableError', () => {
     test('returns true for error with statusCode 403 and error free_mode_unavailable', () => {
-      const error = { statusCode: 403, error: 'free_mode_unavailable', message: 'Free mode is not available in your country.' }
+      const error = {
+        statusCode: 403,
+        error: 'free_mode_unavailable',
+        message: 'Free mode is not available in your country.',
+      }
       expect(isFreeModeUnavailableError(error)).toBe(true)
     })
 
@@ -80,12 +85,20 @@ describe('error-handling', () => {
     })
 
     test('returns false for 403 with different error code', () => {
-      const error = { statusCode: 403, error: 'account_suspended', message: 'Suspended' }
+      const error = {
+        statusCode: 403,
+        error: 'account_suspended',
+        message: 'Suspended',
+      }
       expect(isFreeModeUnavailableError(error)).toBe(false)
     })
 
     test('returns false for non-403 status with free_mode_unavailable error', () => {
-      const error = { statusCode: 400, error: 'free_mode_unavailable', message: 'Bad request' }
+      const error = {
+        statusCode: 400,
+        error: 'free_mode_unavailable',
+        message: 'Bad request',
+      }
       expect(isFreeModeUnavailableError(error)).toBe(false)
     })
 
@@ -102,9 +115,51 @@ describe('error-handling', () => {
     })
   })
 
+  describe('getCountryBlockFromFreeModeError', () => {
+    test('extracts country block details from free-mode unavailable errors', () => {
+      const error = {
+        statusCode: 403,
+        error: 'free_mode_unavailable',
+        countryCode: 'US',
+        countryBlockReason: 'anonymous_network',
+        ipPrivacySignals: ['vpn', 'hosting', 123],
+      }
+
+      expect(getCountryBlockFromFreeModeError(error)).toEqual({
+        countryCode: 'US',
+        countryBlockReason: 'anonymous_network',
+        ipPrivacySignals: ['vpn', 'hosting'],
+      })
+    })
+
+    test('defaults missing country code to UNKNOWN', () => {
+      const error = {
+        statusCode: 403,
+        error: 'free_mode_unavailable',
+      }
+
+      expect(getCountryBlockFromFreeModeError(error)).toEqual({
+        countryCode: 'UNKNOWN',
+        countryBlockReason: undefined,
+        ipPrivacySignals: undefined,
+      })
+    })
+
+    test('returns null for non-free-mode errors', () => {
+      expect(
+        getCountryBlockFromFreeModeError({
+          statusCode: 403,
+          error: 'account_suspended',
+        }),
+      ).toBe(null)
+    })
+  })
+
   describe('FREE_MODE_UNAVAILABLE_MESSAGE', () => {
     test('mentions unavailability in country', () => {
-      expect(FREE_MODE_UNAVAILABLE_MESSAGE.toLowerCase()).toContain('not available in your country')
+      expect(FREE_MODE_UNAVAILABLE_MESSAGE.toLowerCase()).toContain(
+        'not available in your country',
+      )
     })
   })
 

cli/src/utils/error-handling.ts

@@ -1,6 +1,10 @@
 import { env } from '@codebuff/common/env'
 
 import type { ChatMessage } from '../types/chat'
+import type {
+  FreebuffCountryBlockReason,
+  FreebuffIpPrivacySignal,
+} from '@codebuff/common/types/freebuff-session'
 
 import { IS_FREEBUFF } from './constants'
 
@@ -57,20 +61,38 @@ export const isFreeModeUnavailableError = (error: unknown): boolean => {
   return false
 }
 
-/**
- * Extract the detected countryCode off a free_mode_unavailable error, if the
- * server included one. Used to populate the country_blocked screen after the
- * chat-completions gate rejects a user whose session-level country check did
- * not catch the request first.
- */
-export const getCountryCodeFromFreeModeError = (
+export const getCountryBlockFromFreeModeError = (
   error: unknown,
-): string | null => {
+): {
+  countryCode: string
+  countryBlockReason?: FreebuffCountryBlockReason
+  ipPrivacySignals?: FreebuffIpPrivacySignal[]
+} | null => {
   if (!isFreeModeUnavailableError(error)) return null
-  const candidate = (error as { countryCode?: unknown }).countryCode
-  return typeof candidate === 'string' && candidate.length > 0
-    ? candidate
-    : null
+  const errorDetails = error as {
+    countryCode?: unknown
+    countryBlockReason?: unknown
+    ipPrivacySignals?: unknown
+  }
+  const countryCode =
+    typeof errorDetails.countryCode === 'string' &&
+    errorDetails.countryCode.length > 0
+      ? errorDetails.countryCode
+      : 'UNKNOWN'
+
+  return {
+    countryCode,
+    countryBlockReason:
+      typeof errorDetails.countryBlockReason === 'string'
+        ? (errorDetails.countryBlockReason as FreebuffCountryBlockReason)
+        : undefined,
+    ipPrivacySignals: Array.isArray(errorDetails.ipPrivacySignals)
+      ? errorDetails.ipPrivacySignals.filter(
+          (signal): signal is FreebuffIpPrivacySignal =>
+            typeof signal === 'string',
+        )
+      : undefined,
+  }
 }
 
 /**

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

common/src/types/session-state.ts

@@ -69,6 +69,9 @@ export const AgentOutputSchema = z.discriminatedUnion('type', [
     message: z.string(),
     statusCode: z.number().optional(),
     error: z.string().optional(),
+    countryCode: z.string().optional(),
+    countryBlockReason: z.string().optional(),
+    ipPrivacySignals: z.array(z.string()).optional(),
   }),
 ])
 export type AgentOutput = z.infer<typeof AgentOutputSchema>

common/src/util/error.ts

@@ -198,18 +198,56 @@ export function unwrapPromptResult<T>(result: PromptResult<T>): T {
 export function parseApiErrorResponseBody(responseBody: unknown): {
   errorCode?: string
   message?: string
+  countryCode?: string
+  countryBlockReason?: string
+  ipPrivacySignals?: string[]
 } {
   if (typeof responseBody !== 'string') return {}
   try {
     const parsed: unknown = JSON.parse(responseBody)
     if (!parsed || typeof parsed !== 'object') return {}
-    const result: { errorCode?: string; message?: string } = {}
-    if ('error' in parsed && typeof (parsed as { error: unknown }).error === 'string') {
+    const result: {
+      errorCode?: string
+      message?: string
+      countryCode?: string
+      countryBlockReason?: string
+      ipPrivacySignals?: string[]
+    } = {}
+    if (
+      'error' in parsed &&
+      typeof (parsed as { error: unknown }).error === 'string'
+    ) {
       result.errorCode = (parsed as { error: string }).error
     }
-    if ('message' in parsed && typeof (parsed as { message: unknown }).message === 'string') {
+    if (
+      'message' in parsed &&
+      typeof (parsed as { message: unknown }).message === 'string'
+    ) {
       result.message = (parsed as { message: string }).message
     }
+    if (
+      'countryCode' in parsed &&
+      typeof (parsed as { countryCode: unknown }).countryCode === 'string'
+    ) {
+      result.countryCode = (parsed as { countryCode: string }).countryCode
+    }
+    if (
+      'countryBlockReason' in parsed &&
+      typeof (parsed as { countryBlockReason: unknown }).countryBlockReason ===
+        'string'
+    ) {
+      result.countryBlockReason = (
+        parsed as { countryBlockReason: string }
+      ).countryBlockReason
+    }
+    if ('ipPrivacySignals' in parsed) {
+      const signals = (parsed as { ipPrivacySignals: unknown }).ipPrivacySignals
+      if (Array.isArray(signals)) {
+        result.ipPrivacySignals = signals.filter(
+          (signal): signal is string => typeof signal === 'string',
+        )
+      }
+    }
     return result
   } catch {
     return {}