Add Scamalytics free mode risk scoring

Author: jahooma

common/src/types/freebuff-session.ts

@@ -71,12 +71,20 @@ export type FreebuffSpurStatus =
   | 'suspicious'
   | 'failed'
 
+export type FreebuffScamalyticsStatus =
+  | 'not_checked'
+  | 'clean'
+  | 'suspicious'
+  | 'failed'
+
 export type FreebuffPrivacyDecision =
   | 'allowed_clean'
   | 'ipinfo_suspicious_spur_clean'
   | 'corroborated_block'
   | 'cloudflare_tor_block'
   | 'spur_failed_limited'
+  | 'scamalytics_failed_limited'
+  | 'scamalytics_suspicious_limited'
   | 'ipinfo_failed_limited'
   | 'limited_other'
 
@@ -87,6 +95,8 @@ export type FreebuffPrivacyProviderDecision =
   | 'ipinfo_failed'
   | 'ipinfo_only'
   | 'spur_failed'
+  | 'scamalytics_failed'
+  | 'scamalytics_only'
   | 'corroborated_soft'
   | 'corroborated_hard'
 

docs/environment-variables.md

@@ -6,7 +6,8 @@
 - 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; VPN/proxy/Tor/residential-proxy privacy signals use Spur Context API corroboration. In allowlisted countries, a successful clean Spur result overrides IPinfo privacy signals back to full access, while suspicious or failed Spur lookups fall back to limited access. Cloudflare Tor country detection remains a hard block.
+- `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 or ambiguous results fall back to limited access, and only Cloudflare Tor or strongly corroborated high-risk abuse is blocked entirely.
 - `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/Spur privacy classification. Unsupported countries enter limited Freebuff access. In allowlisted countries, IPinfo privacy signals still receive full access when Spur returns clean context, and fall back to limited access when Spur reports suspicious context or lookup fails. IPinfo lookup failures fail closed into limited access. Cloudflare Tor country detection remains a hard block.
+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. Cloudflare Tor country detection and strongly corroborated high-risk VPN/proxy/Tor abuse remain hard blocks.
 
 Response shapes:
 

packages/internal/src/db/migrations/0055_glossy_gertrude_yorkes.sql

@@ -0,0 +1,5 @@
+ALTER TABLE "free_mode_country_access_cache" ADD COLUMN "scamalytics_ip_privacy_signals" text[];--> statement-breakpoint
+ALTER TABLE "free_mode_country_access_cache" ADD COLUMN "scamalytics_status" text;--> statement-breakpoint
+ALTER TABLE "free_mode_country_access_cache" ADD COLUMN "scamalytics_score" integer;--> statement-breakpoint
+ALTER TABLE "free_mode_country_access_cache" ADD COLUMN "scamalytics_risk" text;--> statement-breakpoint
+ALTER TABLE "free_mode_country_access_cache" ADD COLUMN "risk_score" integer;