Add dev-only env to force Freebuff limited mode

Set FREEBUFF_DEV_FORCE_LIMITED=true on localhost to make free-mode
country resolution return allowed=false, so the limited tier UX can be
exercised without a real geo block. Honored only when
NEXT_PUBLIC_CB_ENVIRONMENT === 'dev'; cache lookups are bypassed for
forced-limited requests so toggling the flag takes effect immediately.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: jahooma

packages/internal/src/env-schema.ts

@@ -69,6 +69,14 @@ export const serverEnvSchema = clientEnvSchema.extend({
     .int()
     .positive()
     .default(60 * 60 * 1000),
+
+  // Dev-only override: when 'true', force free-mode requests to the 'limited'
+  // access tier so the limited UX (single DeepSeek Flash model) can be
+  // exercised on localhost. Ignored unless NEXT_PUBLIC_CB_ENVIRONMENT === 'dev'.
+  FREEBUFF_DEV_FORCE_LIMITED: z
+    .enum(['true', 'false'])
+    .default('false')
+    .transform((v) => v === 'true'),
 })
 export const serverEnvVars = serverEnvSchema.keyof().options
 export type ServerEnvVar = (typeof serverEnvVars)[number]
@@ -131,4 +139,5 @@ export const serverProcessEnv: ServerInput = {
   // Freebuff waiting room
   FREEBUFF_WAITING_ROOM_ENABLED: process.env.FREEBUFF_WAITING_ROOM_ENABLED,
   FREEBUFF_SESSION_LENGTH_MS: process.env.FREEBUFF_SESSION_LENGTH_MS,
+  FREEBUFF_DEV_FORCE_LIMITED: process.env.FREEBUFF_DEV_FORCE_LIMITED,
 }

web/src/app/api/v1/chat/completions/_post.ts

@@ -332,6 +332,9 @@ export async function postChatCompletions(params: {
         ipinfoToken: env.IPINFO_TOKEN,
         ipHashSecret: env.NEXTAUTH_SECRET,
         allowLocalhost: env.NEXT_PUBLIC_CB_ENVIRONMENT === 'dev',
+        forceLimited:
+          env.NEXT_PUBLIC_CB_ENVIRONMENT === 'dev' &&
+          env.FREEBUFF_DEV_FORCE_LIMITED,
       })
       freebuffAccessTier = getFreeModeAccessTier(countryAccess)
 

web/src/app/api/v1/freebuff/session/_handlers.ts

@@ -37,6 +37,9 @@ async function getCountryAccess(
         ipinfoToken: env.IPINFO_TOKEN,
         ipHashSecret: env.NEXTAUTH_SECRET,
         allowLocalhost: env.NEXT_PUBLIC_CB_ENVIRONMENT === 'dev',
+        forceLimited:
+          env.NEXT_PUBLIC_CB_ENVIRONMENT === 'dev' &&
+          env.FREEBUFF_DEV_FORCE_LIMITED,
       },
     })
   )

web/src/server/free-mode-country-access-cache.ts

@@ -146,7 +146,7 @@ export async function getCachedFreeModeCountryAccess(params: {
   const clientIp = extractClientIp(req)
   const clientIpHash = hashClientIp(clientIp, options.ipHashSecret)
 
-  if (clientIpHash) {
+  if (clientIpHash && !options.forceLimited) {
     try {
       const cached = await cacheStore.get({
         userId,

web/src/server/free-mode-country.ts

@@ -73,6 +73,12 @@ export type FreeModeCountryAccessOptions = {
   ipinfoToken: string
   ipHashSecret?: string
   allowLocalhost?: boolean
+  /** Dev-only escape hatch: when true (and `allowLocalhost` is also true),
+   *  the localhost bypass returns `allowed: false` so callers exercise the
+   *  limited Freebuff tier instead of full. Cache writes/reads are skipped
+   *  for these requests (clientIpHash is nulled) so flipping the flag takes
+   *  effect on the next request without manual cache eviction. */
+  forceLimited?: boolean
 }
 
 const LOCALHOST_IPS = new Set(['::1', '::ffff:127.0.0.1'])
@@ -216,6 +222,20 @@ export async function getFreeModeCountryAccess(
     !cfCountry &&
     (!clientIp || isLocalhostIp(clientIp))
   ) {
+    if (options.forceLimited) {
+      return {
+        allowed: false,
+        countryCode: 'US',
+        blockReason: 'country_not_allowed',
+        cfCountry: null,
+        geoipCountry: null,
+        ipPrivacy: { signals: [] },
+        hasClientIp: Boolean(clientIp),
+        // Null hash skips the country-access cache so toggling the env var
+        // takes effect immediately without evicting prior allowed=true rows.
+        clientIpHash: null,
+      }
+    }
     return {
       allowed: true,
       countryCode: 'US',