urlsafe

Documentation

Overview

Package urlsafe holds the one URL-scheme allow-list every surface that renders a caller-supplied URL runs through.

It exists because the same ~40-line guard had been re-derived five times — framework/ui.safeURL, framework/uihost.isSafeHeadURL, framework/crud.isSafeMediaURL, framework/experimental/apiversions, and core-ui/patterns/combobox.safePushHref — while core-ui/html, the layer all of them render through, had none. Copies drift; a copy that does not exist is worse. New URL sinks call this package rather than growing a sixth copy.

Index

• func Clean(u string, p Policy) string
• func CleanAnchor(u string) string
• func OK(u string, p Policy) bool
• type Policy

Functions

func Clean

func Clean(u string, p Policy) string

Clean returns u when OK(u, p), and "" otherwise. Convenient for the common `attr = urlsafe.Clean(caller, urlsafe.Anchor)` shape where an empty value means "omit the attribute".

func CleanAnchor

func CleanAnchor(u string) string

CleanAnchor returns u when it is safe to render as an href / action / formaction value (http(s), relative, fragment, mailto, tel) under the Anchor policy, and "" otherwise. It is the one shared helper for anchor- style URL sinks; framework/ui and the breadcrumbs, nestedlist and tree patterns all delegate here instead of each re-wrapping Clean(u, Anchor).

func OK

func OK(u string, p Policy) bool

OK reports whether u may be rendered into a URL attribute under p.

Rejected for every policy, before any scheme check:

• C0 control bytes and DEL, which split attributes and headers
• percent-encoded CR/LF, which smuggles a header line past any consumer that decodes the URL before re-emitting it
• protocol-relative (`//host/…`) references, which silently inherit the page scheme and are ambiguous about origin trust

The empty string is not a URL and is rejected; callers that want to treat "" as "no URL" should check for it before calling.

Types

type Policy

type Policy int

Policy names the scheme set a surface accepts. The split is not decoration: `mailto:` on an <a href> is a feature and `mailto:` on an <img src> or <script src> is a caller mistake at best.

const (
	// Anchor is for navigational URLs the user activates: <a href>,
	// <form action>, <area href>. Accepts http, https, mailto, tel, plus
	// relative, absolute-path, query-only and fragment-only references.
	Anchor Policy = iota

	// Resource is for URLs the browser fetches on its own: <source src>,
	// <script src>, <link href>, and head/meta URLs. Accepts http and
	// https plus relative references — nothing else.
	Resource

	// ImageSource is Resource plus inline raster `data:` URIs, for the one
	// sink where those are a feature rather than a mistake: <img src>.
	//
	// It is a separate policy precisely so the loosening cannot reach
	// <script src> or <link href>, where a data: URI is a code-execution
	// path. Only the raster media types this project's image pipeline can
	// produce are accepted; `data:image/svg+xml` is excluded because SVG is
	// a markup surface, and relying on browsers keeping img-loaded SVG
	// script-disabled is a weaker guarantee than never emitting it.
	ImageSource
)