Skip to content

feat(browser): let the operator list loopback origins the built-in panel may open - #17657

Merged
buluoray merged 2 commits into
mainfrom
fix/browser-local-origins-10126
Oct 11, 2026
Merged

buluoray merged 2 commits into
mainfrom
fix/browser-local-origins-10126

Conversation

@buluoray

@buluoray buluoray commented Oct 7, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Let the user name the exact local dev-server origins (e.g. localhost:5173) that the built-in Browser panel may open, while every other loopback, private and link-local address stays refused.

The native browser MCP tool refuses every non-public navigate target and redirects the agent to playwright-cli. A frontend developer who watches the built-in panel therefore cannot have the agent open their own Vite dev server in it at all, and the issue reporter says the playwright-cli fallback does not work for them.

Why it matters

Previewing one's own local app is the most common reason a frontend user wants the agent to drive a browser. Today the panel they are already watching cannot do it, so that workflow stalls on a fallback that may not work on their machine.

Not a goal

  • No Settings → Browser UI. This draft adds the config key only (kirocrew config set dashboard.browser_local_origins '["localhost:5173"]'). A list editor is a follow-up once the shape is agreed, hence Refs, not Closes.
  • No private/LAN addresses, bare hosts, wildcards or port ranges. One entry opens one loopback port.
  • No change to the playwright-cli path, its approval prompt, or the URL gate on ops other than navigate.

What changed (motivation → approach → change)

Goal → an explicit operator exception to the public-only navigate gate, narrow enough that it cannot reach the gateway's control plane → a new dashboard.browser_local_origins list plus a second, exact-match predicate in the tool.

  • config/sections.py: new field browser_local_origins: list[str] (default []) and coerce_browser_local_origins(). It keeps an entry only when it is exactly localhost, 127.0.0.1 or [::1], then : and an ASCII port in 1-65535, rebuilt canonically. It drops everything else: no port, scheme, path, userinfo, *.localhost, alternate IPv4 encodings, other 127/8 addresses, LAN addresses, non-strings, and a non-list value.
  • mcp_tools/browser.py: _navigate_target_is_allowed_local(url, allowed) runs the same backslash/whitespace/control-character refusals as the public gate. It refuses any userinfo (@ in the netloc) and fills the default port in from the scheme. It then requires the URL's own host:port to equal an entry byte for byte. The gateway's API port (mcp_core._api_port()) is refused even when listed, and an unknowable port refuses too. _allowed_local_origins() reads the config on every call and fails closed to empty. That is the opposite polarity from _use_builtin_browser, because a read error must never widen the gate. navigate now passes when the URL is public OR an allowed local origin. The refusal text names the setting and tells the agent to ask the user instead of editing it.
  • Why the agent cannot grant itself access: config.json is a read-only leaf inside the sandbox (sandbox._CREW_READONLY_LEAVES), and PUT /api/dashboard/config does not accept the key. With sandbox: off that fence is gone, as it is for every other setting.
  • config/prompt.md, docs/system-specs/modules/browser.md and config-baseline.json are updated to describe the exception and its accepted residual.

Backwards compatibility

Compatible: the new key defaults to an empty list, which leaves the existing navigate gate exactly as it is. No existing key, validator or caller changes.

Removes nothing: the change only adds an opt-in exception. Every target refused today is still refused unless the operator lists it.

Tests

test/test_browser_local_origins.py (35 cases):

  • The coercer keeps the four valid shapes and drops a duplicate plus 19 invalid shapes (including a 5,000-digit port, which is dropped rather than raising). It also fails closed on non-list input, and the loader applies it.
  • The matcher admits listed origins (including case, https and IPv6). It refuses unlisted ports, the default port when that port is not listed, a listed address under a different spelling, 0x7f000001/2130706433, *.localhost, the trailing-dot form, both userinfo tricks, backslash/tab differentials, non-http schemes, an invalid port, LAN addresses, and the gateway port even when listed. It also refuses when the gateway port is unknowable or the list is empty.
  • End to end, a listed dev server is POSTed to the panel. Unlisted, gateway and IMDS targets are refused without a POST, and the config reader fails closed.

Mutation-checked, each turning the new file red: dropping the gateway-port check (3 failures), removing the exception from the tool (1), dropping the userinfo refusal (1), and accepting any host in the coercer (2), and dropping the port length cap (1, a ValueError past the int digit limit). The existing test/test_mcp_browser_tool.py refusal matrix still passes unchanged: an empty list keeps http://localhost:8080/ and http://[::1]/ refused.

Run with pytest -n0 by path: the two files above plus test_config_baseline.py, test_config_module_boundaries.py and test_config_refactor_contract.py. 124 passed.

Manual verification

Not driven against a live Electron panel: this Linux host has no desktop build. Only the tool's admission decision changes, and the unit tests cover it end to end up to the bus POST. The panel's own handling of a loopback URL is unchanged and was already reachable through the web-preview marker. Windows/macOS behaviour is unverified on this host, but nothing in the change is platform-specific.

Related Issues

Refs #10126

Decision for the owner

Should the built-in panel ever open a local origin, and if so, under what threat model? This draft says yes, but only for exact loopback host:port entries the operator writes into config (never the gateway's own port, never a bare host or LAN address), because that unblocks the dev-server case while the agent cannot add entries to the list itself; I rejected a host-only or per-session approval-prompt design as wider and more complex.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

Contributions are accepted under the project's Apache-2.0 license.

@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 7, 2026
@github-actions

github-actions Bot commented Oct 7, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 9d71d4a3bbfc6ffb7dcb07a3d17aca8ccb6f8d60 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

First-Principles-Verdict: PASS

Check before merge: no one has run this against a real Electron panel. Open a listed localhost:<port> and confirm it loads and the agent can drive it.

What this change ships

Inventory (5 items) — 5 justified

Intent: let a frontend developer have the agent open and drive their own local dev server in the built-in Browser panel they are already watching. This is an ADDITION (opt-in; Refs #10126).

  1. New opt-in setting dashboard.browser_local_origins; when it is empty, navigate behaves exactly as before — justified
  2. navigate opens a URL whose host:port exactly matches a listed loopback entry — justified
  3. The gateway's own API port is refused even when listed, and so is any URL when the gateway port is unknown — justified
  4. The navigate refusal now names the setting and gives the agent a kirocrew config set command to pass to the user — justified
  5. The system prompt sentence now mentions the listed-origin exception, and the prompt byte ceiling rises from 40,725 to 40,850 — justified

[FIRST-PRINCIPLES-REVIEWED] 9d71d4a

Description read

[DESCRIPTION-READ] f71a09599ce2f8a20c6769abbffda99ffcef7ddba182faebdf4d5cb18f207d45

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Oct 7, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 9d71d4a3bbfc6ffb7dcb07a3d17aca8ccb6f8d60 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

The diff raises the prompt byte ceiling in test_prompt_compact_contract.py (40_725 → 40_850), but the description never mentions it. A maintainer should approve that budget increase explicitly.

[DESIGN-REVIEWED] 9d71d4a

Description read

[DESCRIPTION-READ] cfb9bd7a784ede9bf8e4d56e45a4440fe5488f3b93962ef8306d7d0e77c760cc

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 7, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 9d71d4a3bbfc6ffb7dcb07a3d17aca8ccb6f8d60 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 9d71d4a

Verdict parsed from the review's SHA-scoped output markers for commit 9d71d4a3bbfc6ffb7dcb07a3d17aca8ccb6f8d60.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 9d71d4a3bbfc6ffb7dcb07a3d17aca8ccb6f8d60: <one-sentence reason>

@github-actions

github-actions Bot commented Oct 7, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 9d71d4a3bbfc6ffb7dcb07a3d17aca8ccb6f8d60 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 9d71d4a

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 9d71d4a3bbfc6ffb7dcb07a3d17aca8ccb6f8d60: <one-sentence reason>

@buluoray
buluoray force-pushed the fix/browser-local-origins-10126 branch 2 times, most recently from cfd6155 to 705fc22 Compare October 7, 2026 08:45
@buluoray

buluoray commented Oct 7, 2026

Copy link
Copy Markdown
Contributor Author

Dispositions for the review lanes (head 705fc22c86):

  • GPT 6.1 BLOCKING (sections.py int(port_text) on an oversized port): fixed rather than overridden. The coercer now caps the port at 5 digits before int(), so a 5,000-digit entry is dropped instead of raising past Python's int-string limit and aborting config load. test_coercer_keeps_only_loopback_with_explicit_port now carries that entry and a six-digit 000080. Removing the cap turns the test red with the exact ValueError: Exceeds the limit (4300 digits).
  • Design (suggestion: warn when the loader drops a malformed entry): acknowledged and deferred. A warning belongs in kirocrew config set validation or the Settings list editor, which is the follow-up this draft names under "Not a goal". Silent drop matches how the existing gitlab_hosts and jira_hosts coercers behave.
  • First Principles (drive a listed origin in a real desktop build before merge): agreed. This needs a manual check on a desktop build; the Linux host this draft was built on has none. It is listed under Manual verification in the description.
  • Opus: no findings.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 7, 2026
@buluoray
buluoray force-pushed the fix/browser-local-origins-10126 branch from 705fc22 to 1ca0dbb Compare October 7, 2026 09:22
@github-actions github-actions Bot added readiness: checking Automated validation is still running merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: action required A blocking check or review needs attention labels Oct 7, 2026
@buluoray
buluoray marked this pull request as ready for review October 11, 2026 02:19
@buluoray
buluoray requested review from a team and KiroCrewCaptain as code owners October 11, 2026 02:19
@buluoray
buluoray enabled auto-merge (squash) October 11, 2026 02:19
@buluoray
buluoray requested a review from bolichen97 October 11, 2026 02:19
@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Oct 11, 2026
@buluoray
buluoray force-pushed the fix/browser-local-origins-10126 branch from 1ca0dbb to f607a65 Compare October 11, 2026 02:56
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Oct 11, 2026
@buluoray

Copy link
Copy Markdown
Contributor Author

Conflict-only rebase onto current main (f607a65). The one conflict was the SSRF-gate comment in src/kiro_crew/mcp_tools/browser.py: kept main's 'ordinary shell approval ladder' wording and this PR's operator-allowlist sentence. range-diff shows no change to this PR's own lines.

@github-actions

github-actions Bot commented Oct 11, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 9d71d4a3bbfc6ffb7dcb07a3d17aca8ccb6f8d60 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Advisory — does not block merge.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 11, 2026
@buluoray

Copy link
Copy Markdown
Contributor Author

Pushed d9fe079 for the red test_each_selected_prompt_stays_under_its_byte_ceiling[prompt.md] (40953 > 40725 after the rebase): this PR's Browser-section sentence put prompt.md over budget. Shortened the added sentence (same rule: listed loopback host:port only, never add one yourself) and raised the ceiling to 40_850, which the test's own comment allows when a new rule earns its space; 20 bytes of headroom, as before. The Backend Lint isort red on test/test_crew_log_types.py is inherited from main and not touched here.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 11, 2026
…nel may open

The native browser tool refuses every non-public navigate target, so the
built-in panel cannot open the user's own dev server. Add
dashboard.browser_local_origins: exact loopback host:port entries
(localhost, 127.0.0.1 or [::1] with a required port). The coercer drops
every other shape; the tool admits a navigate whose own host:port equals
an entry byte for byte, after the same parser-differential refusals,
with userinfo refused and the gateway's own port refused even when
listed. Empty by default, read fresh per call, fails closed.

Refs #10126
…budget

Shorten the added Browser-section sentence and raise the prompt.md ceiling
by the rule's remaining bytes, keeping 20 bytes of headroom as before.
@buluoray
buluoray force-pushed the fix/browser-local-origins-10126 branch from d9fe079 to 9d71d4a Compare October 11, 2026 03:53
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Oct 11, 2026

@iamwhatever iamwhatever left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This PR adds an opt-in dashboard.browser_local_origins list (default empty) so the native browser tool's navigate can open exact loopback host:port origins the operator wrote, like a Vite dev server, while everything else non-public stays refused. That solves the reported gap without loosening the public-only gate for anyone who does not opt in. I read the full diff and tried to get past the gate. The coercer only keeps localhost, 127.0.0.1 or [::1] with a 1-65535 port. The matcher refuses localhost.:5173, [::ffff:127.0.0.1], [0:0:0:0:0:0:0:1], 0x7f000001/2130706433, *.localhost, userinfo (localhost:5173@evil), %40 in the host, backslash/tab/control bytes, a bare default port that is not listed, and the gateway's own API port even when listed. It fails closed if config or the gateway port can't be read. #@evil lands in the fragment for both urlsplit and the browser, so the two parsers agree. I also checked that the agent cannot add entries itself: config.json is in sandbox._CREW_READONLY_LEAVES, the dashboard_config PUT only takes use_builtin_browser, and the generic PATCH /api/config/kirocrew is owner-gated (require_owner_dashboard_request). Redirects or links from a listed page are the same residual a public page already has, and the spec says so. Checks are green on 9d71d4a (two commits, within the limit), it is mergeable on main, all lanes PASS, and there are no open change requests. — crew-pr-reviewer (deep re-check)

@buluoray
buluoray merged commit 40fd5ca into main Oct 11, 2026
148 of 149 checks passed
@buluoray
buluoray deleted the fix/browser-local-origins-10126 branch October 11, 2026 06:04
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 11, 2026
@l3aki l3aki mentioned this pull request Nov 1, 2026
1 task done
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants