feat(server): let a request name the tab that relays it

[chrischall]

Closes #203.

The gap

request() derives the relay tab from the request's own host (ws-server.ts), and the fetch handler matches it strict-prefix (background.ts). That's correct for app hosts — the existing comment's photos.x.com / www.x.com reasoning is sound — but it assumes every host can have a tab.

API hosts can't. api.creditkarma.com serves no HTML app; a tab opened there has no content script (1 URL match, none responded). So with a profile declared for the apex and a signed-in www tab open, this was unsatisfiable:

$ fpx post-json https://api.creditkarma.com/graphql @body.json -p creditkarma
bridge error: no tab matching https://api.creditkarma.com/

Meanwhile that www tab can issue the cross-origin fetch perfectly well — CK's own web app does it for every GraphQL call.

The change

viaTab on RequestOpts / BodylessRequestOpts, --via-tab <url> on get / post-json / request. The default is untouched, so the photos.x.com case is unaffected — you only get the override by asking for it.

Verified live, same command that failed above:

$ node packages/cli/dist/index.js post-json https://api.creditkarma.com/graphql @body.json \
    -p creditkarma --via-tab https://www.creditkarma.com/ \
    -H 'ck-client-name: prime_web' -H 'ck-client-version: 2.0.31'
{"errors":[{"message":"An error occurred."}],"data":{"prime":null}}

A real GraphQL response from api.creditkarma.com, relayed through the www tab. (The error body is just the missing bearer — the point is that it reached the origin at all.)

Security

viaTab is guarded with assertUrlInDomains, exactly like the request URL. It widens which tab performs the fetch, never which origins are reachable; the declared-domain set approved at pair time stays the boundary. Malformed values throw naming the option rather than failing deep in the bridge. Both are tested.

Matching stays prefix-based, so https://www.example.com/ accepts any page on that host and a deeper path pins one specific page — tested.

Observation worth a separate issue

While tracing this I noticed handleFetchRequest gates req.init.url against declared domains but not req.init.tabUrl, and content scripts inject on <all_urls>. So a consumer calling the lower-level fetch() directly can already relay through a tab on an undeclared domain. The blast radius looks small — the request URL is still gated, so it's the page's origin being borrowed rather than its data being read — but it's an unenforced boundary, and this PR deliberately does not rely on it (hence the server-side guard). I left it alone rather than widen this PR's scope; say the word and I'll file it.

Tests

1154 pass (up from 1148). packages/server/tests/via-tab.test.ts covers the default, the override for absolute and relative paths, the declared-domain guard, subdomain/path forms, and malformed input. CLI tests cover flag parsing across all three verbs and the threading into server.request. Help text and CLAUDE.md updated.

🤖 Generated with Claude Code

https://claude.ai/code/session_012o2nXwu7tov6j7ciBEpigo

[claude]

Claude finished @chrischall's task in 1m 59s —— View job

---

Reviewing PR #207

• Read CLAUDE.md for conventions
• Read PR diff
• Review server-side changes (ws-server.ts, via-tab.test.ts)
• Review CLI changes (args.ts, main.ts, verbs/fetch.ts, tests)
• Post findings and verdict

Summary

Clean, well-scoped addition. viaTab on RequestOpts/BodylessRequestOpts is threaded correctly from CLI flag → Command → runFetch → FetchproxyServer.request, validated as a URL and gated through the existing assertUrlInDomains boundary (packages/server/src/ws-server.ts:1797-1806) before overriding tabUrl. Default behavior (https://{host}/) is untouched when viaTab is omitted, matching the PR's stated intent. Tests cover the default, override (absolute + relative paths), off-domain rejection, subdomain/path prefix matching, and malformed input on both the server and CLI sides.

The 1.12.0+ doc annotations (ws-server.ts:389, :577) match the pre-existing convention already on main (e.g. FetchproxyScopeError docs at :519, :547 from PR #205) of annotating with the next unreleased version pre-emptively — not a new inconsistency introduced here.

Note: I was unable to run npm test/npm run typecheck in this environment (tool approval required for non-read-only Bash), so test-suite-green status is based on static review of the new/changed test files, not an actual run.

Nits

• 🟡 --via-tab isn't validated at the CLI layer the way the request URL is (assertUrlOnProfile in packages/cli/src/verbs/fetch.ts:52, called from runFetch at :75, throws a UsageError → exit 1). A malformed or off-domain --via-tab instead surfaces from the server as a generic thrown Error, which mapBridgeError (packages/cli/src/bridge-errors.ts) falls through to the other bucket and exit code 2 (bridge) rather than 1 (usage). Minor UX inconsistency, not a functional bug — the value is still safely rejected either way.

Observation (out of scope, author already flagged)

The PR body itself notes handleFetchRequest gates req.init.url against declared domains but not req.init.tabUrl on the extension side, deliberately not relied upon here since the server-side guard covers it. Worth a follow-up issue as the author suggests, not a blocker for this PR.

Verdict: pass

[github-actions]

✅ Auto-review verdict: pass — Well-scoped, correctly wired, and well-tested addition of a viaTab/--via-tab override for relay-tab selection; only a minor CLI-vs-server exit-code inconsistency on malformed input.
📋 Tracking follow-ups: #209

[chrischall]

Correcting the evidence in this PR

The verification I gave was weaker than it looked, and I should have caught that before opening it. Two gaps:

1. No control. I showed one successful --via-tab call returning a body, and asserted that proved the relay. It didn't — with no matching failure run in the same bridge state, the success wasn't attributable to the flag.
2. The motivation was asserted, not tested. I claimed an API host "serves no HTML app" so its tab can never relay. My only supporting run had also reported a downed service worker and had explicitly told me to refresh the page and retry — and I never did. It could have been service-worker eviction.

Both have now been tested properly. The conclusion is unchanged, but the reasoning is different and sharper than what the PR body says.

Control, back to back, same bridge state

$ node packages/cli/dist/index.js post-json https://api.creditkarma.com/graphql @body.json -p creditkarma
bridge error (protocol): no tab matching https://api.creditkarma.com/ — open a tab on that host…

$ node … --via-tab https://www.creditkarma.com/
HTTP 400 https://api.creditkarma.com/graphql

Same command, same seconds apart, one flag different: unroutable → real origin response.

Why the API-host tab genuinely cannot work

I opened a tab on https://api.creditkarma.com/, reloaded it, and retried without the flag. It failed twice with 1 URL match, none responded. Then I inspected the tab:

{"url":"chrome-error://chromewebdata/",
 "title":"api.creditkarma.com",
 "bodyStart":"This api.creditkarma.com page can't be found\nNo webpage was found for the web address: https://api.creditkarma.com/"}

https://api.creditkarma.com/ 404s, so Chrome renders its own error document at chrome-error://chromewebdata/, and Chrome does not inject content scripts into chrome-error:// pages — the <all_urls> match never applies. Meanwhile chrome.tabs.query still reports the tab's URL as the requested https URL, which is precisely why the extension says "1 URL match, none responded": the URL matches, the document behind it can't host a relay.

So no amount of refreshing fixes it, and the "refresh the page to inject the content script" advice in that error is unactionable for this class of host.

What that changes

Nothing about the code — the guard, the default, and the tests all stand. But the PR body's framing ("serves no HTML app") is imprecise; the operative fact is 404 → chrome-error:// document → no content script, permanently. Any host that doesn't serve a real document at the path you'd open is in the same position, including one that 404s at / while serving a working API underneath — which is the common case.

Worth folding that mechanism into the viaTab doc comment; happy to do it in the follow-up that addresses #209.

🤖 Generated with Claude Code