Documentation
¶
Overview ¶
Package browser provides a safe entry point for opening URLs in the user's default browser or mail client.
The design goal is to constrain every URL-opening code path in the codebase through a single validation point so that:
- Only scheme://url of types https, http, and mailto are passed to the OS. Dangerous schemes such as file://, javascript:, data:, and custom protocol handlers are rejected.
- Oversize URLs (above 8 KiB, chosen to sit below all supported platforms' command-line length limits) are rejected.
- URLs containing ASCII control characters or NUL bytes are rejected before they reach any platform URL handler.
Callers must never invoke the underlying OS URL opener (such as github.com/cli/browser or exec.Command("open"|"xdg-open"|"rundll32")) directly. All URL-opening in GTB routes through OpenURL.
mailto: and caller responsibility ¶
OpenURL validates only the scheme and the URL's overall shape. It cannot detect header-injection attacks in mailto: URLs such as an attacker-supplied cc=, bcc=, or body= parameter. Callers constructing mailto: URLs from user-influenced data must escape every parameter using url.QueryEscape. See the EmailDeletionRequestor in pkg/telemetry for an example.
Context cancellation ¶
The underlying URL opener is not context-aware; once the OS spawns a browser or mail client process, OpenURL cannot cancel it. Callers pass a context so that pre-open cancellation (e.g. the enclosing command was cancelled before the opener ran) is respected.
This package closes M-5 from the 2026-04-02 security audit. See docs/development/specs/2026-04-02-url-scheme-validation.md for the full threat model and design rationale.
Index ¶
Constants ¶
const MaxURLLength = 8192
MaxURLLength is the maximum accepted length for a URL, in bytes.
The value is set conservatively below OS command-line limits (Windows: ~32 KB, Linux: ~128 KB ARG_MAX, macOS: ~256 KB) so a single constant is safe on all supported platforms. 8 KiB is generous for legitimate URLs including mailto: with long bodies.
Variables ¶
var AllowedSchemes = []string{"https", "http", "mailto"}
AllowedSchemes lists the URI schemes that OpenURL permits.
Scheme comparison is case-insensitive per RFC 3986. The list is intentionally not configurable — extending it requires a code change and a security-review sign-off.
var ErrDisallowedScheme = errors.New("disallowed URL scheme")
ErrDisallowedScheme is returned when a URL's scheme is not in AllowedSchemes.
var ErrInvalidURL = errors.New("invalid URL")
ErrInvalidURL is returned when a URL fails hygiene validation: empty, too long, contains control characters, or fails to parse.
Functions ¶
func OpenURL ¶
OpenURL validates rawURL and, if accepted, opens it in the user's default browser or mail client.
Validation runs fail-fast in this order:
- Length ≤ MaxURLLength
- No ASCII control characters (0x00–0x1F, 0x7F)
- net/url.Parse succeeds
- Scheme matches AllowedSchemes (case-insensitive)
- Context not cancelled
Returns ErrInvalidURL wrapped with a hint for hygiene failures, ErrDisallowedScheme with a hint for scheme failures, the context's error for cancellation, or a wrapped error from the underlying opener for OS-level failures.
The URL is never logged by this function: callers that wish to surface a diagnostic message to the user should extract the scheme and host from their own copy of rawURL rather than rely on errors generated here.
Types ¶
type Opener ¶
Opener is the signature of the function that performs the actual OS URL open. The default is github.com/cli/browser.OpenURL. Callers may override via WithOpener — primarily for testing, but also to integrate with custom OS handlers.
type Option ¶
type Option func(*options)
Option configures OpenURL.
func WithOpener ¶
WithOpener replaces the default OS URL opener.
Primarily intended for testing (so tests do not launch real browsers) but also useful for custom OS integrations. Passing nil is treated as "use the default".
Source Files