Anti-ban hardening: trust-score-aware operation, egress policy, and residual wire divergences

[trefeon]

Context

Full audit of the FreeBuff trust-score system (reverse-engineered from reference/freebuff/ CLI 0.0.149) vs. freebuff-proxy's anti-ban posture. An account used via the SG datacenter VPS was banned after an upstream 403 storm; investigation shows trust system behavior we need to formalize.

Trust system summary (upstream freebuff-trust.ts):

• Levels: new(0) / verified(25) / established(50) / core(75); DB-failure fail-open = established.
• Points earn, penalties only CAP: 8 caps — past_enforcement→verified, anonymous_network→verified (live risk ≥75), past_corroborated_egress→verified, third_party_client→verified (sticky foreign tool schema), past_privacy_egress→established, signup_privacy_egress→established, shared_signup_network→established (≥8 per /24), shared_mailbox→verified (≥3).
• Spend ceilings compose by minimum; SG/CN restricted cohort = $0.50/day with 2× hard cut.
• ipPrivacySignals wire set: anonymous|vpn|proxy|tor|relay|res_proxy|hosting|service.

Findings

1. Egress IP class dominates trust exposure. Datacenter/VPN/hosting egress → restricted $0.50 cohort + anonymous_network cap. The SG VPS (Azure hosting ASN) flips a token from full to limited and is the documented ban contributor; residential egress is the only full-tier route.
2. v0.11.3-era PREFER_MAX_MODELS over-upgrade produced a 403 free_mode_invalid_agent_model storm → upstream escalated to status: banned. Fixed in v0.11.4 (tier-aware gating), but the incident validated the risk class.
3. Bridge mode + shared-router fan-in (9router → many parallel per-client sessions from one egress) increases fingerprinting correlation; pooled mode centralizes session lifecycle.
4. third_party_client sticky cap: any non-CLI tool schema on the free-mode wire (agentic clients with custom tools) can cap an account at verified forever + $0.50 cohort. Needs a strategy (tool-schema tolerance mapping to official base2-free schemas?).
5. Residual wire divergences (audit): (a) ProbeAccount sends x-freebuff-include-unused-rate-limits: 1 — Web/Desktop-only header the CLI never sends, cited against third-party proxies (netroindonesia/quota.js); (b) session/streak/agent-runs/me paths carry ai-sdk UA where the CLI uses bun default (coherent, low risk); (c) stop:["cb_easp"] injection unverified against a live capture.
6. Proxy RiskEngine + local ledger approximate server trust but cannot see the real level except the pre-join standing block (already surfaced on the dashboard).

Proposed work items

• P0 Decide/implement residential-egress guidance or enforcement: document Tailscale/WireGuard exit-node pattern for VPS deployments; optionally warn at startup when egress ASN is hosting/datacenter (doctor + startup log).
• P1 Drop x-freebuff-include-unused-rate-limits from ProbeAccount (internal/upstream/client.go ~1019); read unused limits from full admissions.
• P1 Streaming/request 403-class escalation guard: when N free_mode_invalid_agent_model/model_mismatch 403s occur in a short window for one token, surface a hard operator warning (webhook event) instead of letting retries amplify.
• P2 Research third-party-client tool-schema tolerance: map common agent tool schemas (read/write/bash/glob/todo) to official base2-free schemas where possible; otherwise document the sticky-cap risk per client.
• P2 Session-safety knob: per-egress token cap advisory (≥8 accounts per /24 → shared_signup_network cap) mirrored into -doctor + dashboard.
• P3 Verify cb_easp stop sentinel against live capture; remove or keep with evidence.
• P3 Consider surfacing standing/cappedBy/nextSteps from pre-join session on the dashboard tokens page (we already parse it; render it).

References

• reference/freebuff/common/src/constants/freebuff-trust.ts (+ tests)
• reference/freebuff/common/src/types/freebuff-session.ts
• reference/freebuff/common/src/constants/freebuff-spend-ceilings.ts, freebuff-signup-block.ts, cf-worker-signals.ts
• docs/guides/anti-ban-gap-analysis.md, docs/guides/freebuff-cli-internals.md
• Proxy: internal/stealth/risk.go, internal/upstream/client.go, internal/pool/pool.go, internal/config/config.go

[trefeon]

Scripts audit + hardening (9950d60, all CI green)

Audited every token-minting script under scripts/ against the official CLI's auth flow (reference/freebuff/cli/src/utils/fingerprint.ts, login/login-flow.ts). Findings and fixes shipped:

Fixed

1. UA divergence on the auth surface — gen-freebuff-token.sh/.ps1 and install-freebuff-proxy.ps1 hit /api/auth/cli/code + /status with curl/PowerShell default UAs (a third-party-tool signal on the exact surface cf-worker-signals fingerprints). All now pin the CLI-parity ai-sdk/openai-compatible/1.0.0/codebuff UA. install.sh/install.ps1 already had it.
2. Fingerprint shape divergence — the four scripts minted four different shapes (43-char base62, 48-hex, 64-hex, 43-char base64), none matching the CLI's enhanced-<SHA-256 base64url> (43 chars, -/_ allowed). All now emit the identical 43-char base64url shape; verified enhanced-[A-Za-z0-9_-]{43}.
3. README claimed post-auth /api/v1/me + /api/v1/freebuff/session verification that did not exist. Now implemented in both generators: a zero-cost probe (no x-freebuff-instance-id, no session slot) that prints status/tier/risk and exit 1 refuses to save a banned account — a fresh token can no longer be silently appended dead.
4. Poll cadence — install.sh polled at 4s, install-freebuff-proxy.ps1 at 4s vs the CLI's 5s intervalMs; both now 5s.

Noted (design, documented in README)

• Fingerprints stay random per run (deliberate: multiple accounts on one machine must not share an identifier). The official CLI fingerprint is machine-deterministic; if upstream ever correlates per-run randomness with farm patterns, we'd need a persisted-per-account option. getFingerprintType only validates the enhanced- prefix today.

Pending (issue backlog)

• The ProbeAccount x-freebuff-include-unused-rate-limits divergence (P1) remains open — script probe now avoids it (Bearer + UA only).