Reduce Freebuff VPN false positives with Spur (#714)

Author: jahooma

common/src/types/freebuff-session.ts

@@ -65,6 +65,31 @@ export type FreebuffIpPrivacySignal =
   | 'hosting'
   | 'service'
 
+export type FreebuffSpurStatus =
+  | 'not_checked'
+  | 'clean'
+  | 'suspicious'
+  | 'failed'
+
+export type FreebuffPrivacyDecision =
+  | 'allowed_clean'
+  | 'ipinfo_suspicious_spur_clean'
+  | 'corroborated_block'
+  | 'cloudflare_tor_block'
+  | 'spur_failed_limited'
+  | 'ipinfo_failed_limited'
+  | 'limited_other'
+
+export type FreebuffPrivacyProviderDecision =
+  | 'not_checked'
+  | 'cloudflare_tor'
+  | 'ipinfo_clean'
+  | 'ipinfo_failed'
+  | 'ipinfo_only'
+  | 'spur_failed'
+  | 'corroborated_soft'
+  | 'corroborated_hard'
+
 export interface FreebuffLimitedModeReason {
   /** Present for limited access so the model picker can explain why the
    *  reduced model set is shown without re-running geo/IP logic locally. */

docs/environment-variables.md

@@ -6,6 +6,7 @@
 - Server secrets: validated in `packages/internal/src/env-schema.ts` (used via `@codebuff/internal/env`).
 - 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; hard VPN/proxy/Tor/residential-proxy free-mode blocks require Spur Context API corroboration. In allowlisted countries, a successful clean Spur result overrides IPinfo privacy signals back to full access, while a Spur lookup failure falls back to limited access.
 - `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 allowlisted country and a successful IPinfo privacy check. IPinfo `anonymous`, `vpn`, `proxy`, `tor`, `relay`, `res_proxy`, `hosting`, and `service` signals are blocked; privacy lookup failures fail closed.
+Before any of those state transitions, the handler requires a resolved country and successful IPinfo/Spur privacy checks. Unsupported countries enter limited Freebuff access. In allowlisted countries, IPinfo privacy signals still receive full access when Spur returns clean context, fall back to limited access when Spur lookup fails, and hard-block only when Spur corroborates VPN/proxy/Tor/residential-proxy traffic. IPinfo lookup failures fail closed into limited access.
 
 Response shapes:
 

packages/internal/src/db/migrations/0053_solid_karnak.sql

@@ -0,0 +1,2 @@
+ALTER TABLE "free_mode_country_access_cache" ADD COLUMN "spur_ip_privacy_signals" text[];--> statement-breakpoint
+ALTER TABLE "free_mode_country_access_cache" ADD COLUMN "spur_status" text;

packages/internal/src/db/migrations/0054_clumsy_robin_chapel.sql

@@ -0,0 +1,2 @@
+ALTER TABLE "free_mode_country_access_cache" ADD COLUMN "privacy_decision" text;--> statement-breakpoint
+ALTER TABLE "free_mode_country_access_cache" ADD COLUMN "privacy_provider_decision" text;