Add Scamalytics free mode risk scoring (#746)

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, 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/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 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:
 

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;