feat(ai): Claude serverless proxy for web/PWA (ADR-0016 Track B)

[qnbs]

Summary

PR 3 of 4 in the stacked sequence (stacked on #300 — Claude Track A). Auto-retargets once #300 merges into #299's branch, then again once #299 merges into main.

Browser tabs have no native-HTTP CORS escape hatch, so Anthropic requests from Vercel/Cloudflare Pages deployments now relay through this app's own stateless serverless proxy — its first backend dependency ever.

• api/_shared/claudeProxyCore.ts: platform-agnostic relay core. Mandatory abuse controls (the endpoint is public/unauthenticated by construction — CWE-400): Zod schema validation, 256 KiB body-size cap (checked against both the Content-Length header and the actual body), same-origin check, per-client rate limit (20 req/60s), 20s outbound timeout. Never logs the key/prompt/response — asserted directly in tests.
• api/claude-proxy.ts (Vercel Edge Function) + functions/api/claude-proxy.ts (Cloudflare Pages Function) — thin wrappers around the shared core.
• services/deployTarget.ts: isServerlessProxyCapable() — reuses import.meta.env.BASE_URL (already this codebase's build-time GitHub-Pages-vs-edge marker) to detect whether the proxy can exist on the current deployment.
• streamAnthropic() / testAIConnection get a three-way split: desktop (Track A, unchanged) / proxy-capable web (fetches /api/claude-proxy) / GitHub Pages (throws immediately, before checking for a key).
• AiProviderCard.tsx: extracted the anthropic UI into AnthropicProviderFields.tsx (kept the parent under Biome's cognitive-complexity gate). Desktop and proxy-capable web render the same real key + model UI; only GitHub Pages keeps a warning block, reworded from a generic CORS note to the actual reason.
• docs/SECURITY-THREAT-MODEL.md: new section — this is the one provider whose BYOK key transits infrastructure WorldScript runs, stated plainly.

Test plan

• pnpm run lint / pnpm run typecheck — clean
• pnpm run i18n:check — 2857 keys
• node scripts/audit-tokens.mjs — 160 ≤ baseline
• claudeProxyCore.test.ts (14), claudeProxyEntrypoints.test.ts (3), deployTarget.test.ts (3), aiProviderService.test.ts, AiProviderCard.test.tsx — 126 tests green
• CI — awaiting push

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Claude is now available in supported web deployments through a secure serverless relay.
  • Added clearer Anthropic settings with model selection, API key management, and deployment-specific availability guidance.
  • Desktop installations continue to support direct Claude connections.

• Bug Fixes

  • Improved Claude response handling and connection testing across desktop, web, and static deployments.
  • Added clearer messaging when Claude is unavailable on static-only hosting.

• Documentation

  • Updated security, privacy, routing, provider availability, and project metrics documentation.

• Tests

  • Expanded coverage for proxy security, deployment behavior, connection testing, and localized settings.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
worldscript-studio	Ready	Preview	Jul 30, 2026 10:38pm

[coderabbitai]

Warning

Review limit reached

You’ve reached a temporary PR review limit under our Fair Usage Limits Policy.

Your recent review volume is higher than typical usage, so adaptive limits are currently applied.

Next review available in:25 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 72d2dd0e-d90e-42af-b110-72d08e8d444b

📥 Commits

Reviewing files that changed from the base of the PR and between ab1ddd7 and 4f93f9b.

📒 Files selected for processing (4)

• api/_shared/claudeProxyCore.ts
• api/claude-proxy.ts
• components/settings/AnthropicProviderFields.tsx
• tests/unit/api/claudeProxyCore.test.ts

📝 Walkthrough

Walkthrough

Claude support now routes desktop requests directly to Anthropic and browser requests through validated serverless proxy endpoints, with static-host detection, capability-aware settings UI, localized availability messaging, security documentation, and expanded unit coverage.

Changes

Claude proxy routing

Layer / File(s)	Summary
Validated proxy relay api/_shared/claudeProxyCore.ts, api/claude-proxy.ts, functions/api/claude-proxy.ts, tests/unit/api/*	Adds shared request validation, origin checks, rate limiting, size limits, timeout handling, Anthropic relay behavior, and Vercel/Cloudflare adapters with tests.
Runtime-aware provider flow services/aiProviderService.ts, services/deployTarget.ts, tests/unit/aiProviderService.test.ts, tests/unit/deployTarget.test.ts	Routes Tauri calls directly, browser calls through /api/claude-proxy, and static GitHub Pages deployments to a dedicated unavailable result.
Deployment-aware settings UI components/settings/AiProviderCard.tsx, components/settings/AnthropicProviderFields.tsx, tests/unit/settings/AiProviderCard.test.tsx	Renders Anthropic controls or deployment warnings based on desktop and proxy capability, including proxy notes and model selection.
Localized messaging locales/*/settings.json, public/locales/*/bundle.json	Adds proxy explanations and replaces the generic backend-proxy error with static-host proxy-unavailability messaging.
Documentation and metrics README.md, docs/SECURITY-THREAT-MODEL.md, docs/adr/0016-native-grok-and-claude-providers.md	Documents the Claude trust model, abuse controls, resolved ADR decisions, deployment limits, and refreshed project metrics.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
participant User
participant AiProviderService
participant claudeProxy
participant Anthropic
User->>AiProviderService: Request Claude completion
AiProviderService->>claudeProxy: Send proxy request on supported web deployment
claudeProxy->>Anthropic: Forward validated Messages API payload
Anthropic-->>claudeProxy: Return response
claudeProxy-->>AiProviderService: Return no-store response
AiProviderService-->>User: Stream Claude text

Loading

Possibly related PRs

• qnbs/WorldScript-Studio#272: Both update typed AI connection-test errors and their localized settings messages.
• qnbs/WorldScript-Studio#300: Both modify runtime-specific Anthropic handling in the settings and provider service.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 36.36% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely summarizes the main change: adding a Claude serverless proxy for web/PWA as ADR-0016 Track B.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/claude-track-b-web-proxy

---

_{Comment @coderabbitai help to get the list of available commands.}

[qnbs]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[codeant-ai]

🏁 CodeAnt Quality Gate Results

Commit:ab1ddd71
Scan Time: 2026-07-30 22:15:11 UTC

✅ Overall Status: PASSED

Quality Gate Details

Quality Gate	Status	Details
Secrets	✅ PASSED	0 secrets found
Duplicate Code	✅ PASSED	0.4% duplicated
SAST	✅ PASSED	No security issues
Bugs	✅ PASSED	Rating S: No bugs
IAC	✅ PASSED	Rating S: No issues

View Full Results

[qnbs]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[codecov]

Codecov Report

❌ Patch coverage is 83.87097% with 5 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
services/aiProviderService.ts	78.94%	0 Missing and 4 partials ⚠️
components/settings/AnthropicProviderFields.tsx	88.88%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[coderabbitai]

Actionable comments posted: 8

🧹 Nitpick comments (4)

docs/SECURITY-THREAT-MODEL.md (1)

212-220: 🔒 Security & Privacy | 🔵 Trivial | 💤 Low value

Security Misconfiguration (CWE-346): Origin Validation Error

Reachability: External

Consider qualifying the same-origin control.

The Origin check only constrains browser-driven callers; any non-browser client can set the header freely, so it is not an authentication boundary for scripted abuse (the rate limit and body caps are what bound that case). A one-clause caveat keeps the threat model from being read as stronger than it is.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/SECURITY-THREAT-MODEL.md` around lines 212 - 220, Qualify the
same-origin check in the “Abuse controls” description to state that it
constrains browser-driven callers but is not an authentication boundary for
non-browser clients, which can freely set the Origin header; retain the existing
rate-limit and body-size controls as the protections for scripted abuse.

api/_shared/claudeProxyCore.ts (1)

114-127: 🩺 Stability & Availability | 🔵 Trivial | ⚡ Quick win

rawBody.length counts UTF-16 units, not bytes.

The post-read cap therefore admits bodies well over 256 KiB of actual payload for multi-byte content (the Content-Length header path is bytes, the fallback path is not). Using an encoded byte length keeps both checks on the same unit.

♻️ Align the fallback check with byte length

- if (rawBody.length > MAX_BODY_BYTES) {+ if (new TextEncoder().encode(rawBody).length > MAX_BODY_BYTES) {
return jsonResponse(413, { error: 'Request body too large' });
}

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@api/_shared/claudeProxyCore.ts` around lines 114 - 127, Update the post-read
size check in the request-body handling flow to measure rawBody’s encoded byte
length rather than UTF-16 string length, keeping it consistent with the
content-length header check and the existing MAX_BODY_BYTES limit.

tests/unit/api/claudeProxyCore.test.ts (1)

40-46: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

% 255 wraps and shares rate-limit buckets once the suite grows.

The limiter map is module-level, so a wrapped IP would inherit a previous test's window. A wider address space (or a per-test unique suffix) removes that future flake.

♻️ Wider unique client id space

 function uniqueIp(): string {
ipCounter += 1;
- return `203.0.113.${ipCounter % 255}`;+ return `198.51.100.${Math.floor(ipCounter / 254) % 254}.${ipCounter % 254}`.replace(+ /^(\d+\.\d+\.\d+)\.(\d+)\.(\d+)$/,+ '$1.$3',+ );
}

Simpler alternative: append a per-test counter to a synthetic id such as client-${ipCounter}, since the handler only uses the value as a map key.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@tests/unit/api/claudeProxyCore.test.ts` around lines 40 - 46, Update
uniqueIp() so generated client identifiers never repeat as the test suite grows;
remove the `% 255` wrapping and use a wider synthetic value or a monotonically
increasing per-test suffix while preserving its use as the x-forwarded-for
rate-limit key.

services/aiProviderService.ts (1)

306-317: 🩺 Stability & Availability | 🔵 Trivial | ⚡ Quick win

Add a timeout to the Claude proxy request.
fetch('/api/claude-proxy') only forwards opts.signal, so a stalled same-origin call can leave the stream hanging. Merge the caller signal with AbortSignal.timeout(...) here, as the other request paths do.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@services/aiProviderService.ts` around lines 306 - 317, Update the Claude
proxy request in the fetch call to combine opts.signal with an
AbortSignal.timeout(...) signal, using the same timeout-merging pattern as the
other request paths. Preserve caller cancellation while ensuring stalled
requests are automatically aborted before deliverAnthropicResponse processes the
response.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@api/_shared/claudeProxyCore.ts`:
- Around line 1-5: Update the header cross-reference in
api/_shared/claudeProxyCore.ts lines 1-5 to use functions/api/claude-proxy.ts,
and make the same documentation-only path correction in api/claude-proxy.ts
lines 1-5. No code behavior changes are required.
- Around line 50-61: Update isRateLimited so exceeding
RATE_LIMIT_MAX_TRACKED_CLIENTS evicts only the least-recently-seen client
entries rather than calling rateLimitLog.clear(). Preserve active clients’
timestamp windows while keeping the map bounded, using each client’s most recent
timestamp to identify eviction candidates.
In `@components/settings/AnthropicProviderFields.tsx`:
- Around line 20-26: Add an immediately adjacent single-line `// QNBS-v3: [Grund
/ Impact / Kreativer Mehrwert]` comment above the capability-gated change in
components/settings/AnthropicProviderFields.tsx lines 20-26. Replace the
existing multi-line marker above the new test block in
tests/unit/settings/AiProviderCard.test.tsx lines 387-389 with one single-line
QNBS-v3 comment using the required format.
- Around line 63-89: Localize the Anthropic placeholder and all three model
labels in AnthropicProviderFields using t('key.path') keys. Update the related
AiProviderCard test assertion to validate the localized label/key behavior. Add
the new translation keys to all 19 locale trees and regenerate the runtime
bundles; affected sites are components/settings/AnthropicProviderFields.tsx
lines 63-89 and tests/unit/settings/AiProviderCard.test.tsx lines 427-429.
In `@public/locales/hu/bundle.json`:
- Line 1728: Translate both newly added Hungarian entries in
public/locales/hu/bundle.json: settings.ai.anthropicProxyNote at lines 1728-1728
and settings.ai.testError.proxyUnavailableStaticHost at lines 1872-1872. Add the
corresponding Hungarian source translations and regenerate the bundle,
preserving the proxy/privacy wording and static-host diagnostic details.
In `@public/locales/is/bundle.json`:
- Line 1728: Translate settings.ai.anthropicProxyNote and
settings.ai.testError.proxyUnavailableStaticHost in the source locale files,
then regenerate the bundles. Apply the translations at
public/locales/is/bundle.json lines 1728 and 1872, public/locales/ja/bundle.json
lines 1728 and 1872, and public/locales/ko/bundle.json lines 1728 and 1872;
ensure none of these non-English entries remain in English.
In `@public/locales/pt/bundle.json`:
- Line 1728: Translate the newly added proxy guidance keys in
locales/pt/settings.json into Portuguese, preserving the diagnostic meaning of
the static-host message and the existing message intent. Then regenerate
public/locales/pt/bundle.json using the repository’s standard i18n generation
command so the bundle contains the localized values.
In `@services/deployTarget.ts`:
- Around line 8-19: Replace the BASE_URL comparison in isServerlessProxyCapable
with an explicit build-time capability flag configured only for deployments that
provide api/claude-proxy, including Vercel and Cloudflare builds. Ensure static
Docker/nginx deployments and GitHub Pages custom domains evaluate as
unsupported, while preserving the existing unsupported-deployment fallback
behavior.
---
Nitpick comments:
In `@api/_shared/claudeProxyCore.ts`:
- Around line 114-127: Update the post-read size check in the request-body
handling flow to measure rawBody’s encoded byte length rather than UTF-16 string
length, keeping it consistent with the content-length header check and the
existing MAX_BODY_BYTES limit.
In `@docs/SECURITY-THREAT-MODEL.md`:
- Around line 212-220: Qualify the same-origin check in the “Abuse controls”
description to state that it constrains browser-driven callers but is not an
authentication boundary for non-browser clients, which can freely set the Origin
header; retain the existing rate-limit and body-size controls as the protections
for scripted abuse.
In `@services/aiProviderService.ts`:
- Around line 306-317: Update the Claude proxy request in the fetch call to
combine opts.signal with an AbortSignal.timeout(...) signal, using the same
timeout-merging pattern as the other request paths. Preserve caller cancellation
while ensuring stalled requests are automatically aborted before
deliverAnthropicResponse processes the response.
In `@tests/unit/api/claudeProxyCore.test.ts`:
- Around line 40-46: Update uniqueIp() so generated client identifiers never
repeat as the test suite grows; remove the `% 255` wrapping and use a wider
synthetic value or a monotonically increasing per-test suffix while preserving
its use as the x-forwarded-for rate-limit key.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 0077dbe9-88a9-4865-9972-532fec010d0e

📥 Commits

Reviewing files that changed from the base of the PR and between 6cac0df and ab1ddd7.

📒 Files selected for processing (53)

• README.md
• api/_shared/claudeProxyCore.ts
• api/claude-proxy.ts
• components/settings/AiProviderCard.tsx
• components/settings/AnthropicProviderFields.tsx
• docs/SECURITY-THREAT-MODEL.md
• docs/adr/0016-native-grok-and-claude-providers.md
• functions/api/claude-proxy.ts
• locales/ar/settings.json
• locales/de/settings.json
• locales/el/settings.json
• locales/en/settings.json
• locales/es/settings.json
• locales/eu/settings.json
• locales/fa/settings.json
• locales/fi/settings.json
• locales/fr/settings.json
• locales/he/settings.json
• locales/hu/settings.json
• locales/is/settings.json
• locales/it/settings.json
• locales/ja/settings.json
• locales/ko/settings.json
• locales/pt/settings.json
• locales/ru/settings.json
• locales/sv/settings.json
• locales/zh/settings.json
• public/locales/ar/bundle.json
• public/locales/de/bundle.json
• public/locales/el/bundle.json
• public/locales/en/bundle.json
• public/locales/es/bundle.json
• public/locales/eu/bundle.json
• public/locales/fa/bundle.json
• public/locales/fi/bundle.json
• public/locales/fr/bundle.json
• public/locales/he/bundle.json
• public/locales/hu/bundle.json
• public/locales/is/bundle.json
• public/locales/it/bundle.json
• public/locales/ja/bundle.json
• public/locales/ko/bundle.json
• public/locales/pt/bundle.json
• public/locales/ru/bundle.json
• public/locales/sv/bundle.json
• public/locales/zh/bundle.json
• services/aiProviderService.ts
• services/deployTarget.ts
• tests/unit/aiProviderService.test.ts
• tests/unit/api/claudeProxyCore.test.ts
• tests/unit/api/claudeProxyEntrypoints.test.ts
• tests/unit/deployTarget.test.ts
• tests/unit/settings/AiProviderCard.test.tsx

[qnbs]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[qnbs]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.