Documentation
¶
Overview ¶
Package origin validates and matches the serialized origins that the CORS and CSRF middleware compare against their configured allow lists.
Both middleware carried their own copy of this. `normalizeOrigin` differed by one scheme check, and the subdomain type, its matcher and the wildcard walk were character for character the same in `middleware/cors/utils.go` and `middleware/csrf/helpers.go`. The one real difference is named here as SchemePolicy rather than left to be inferred from which copy you are reading:
- CORS accepts any scheme, because Access-Control-Allow-Origin is echoed for schemes beyond http(s) and the browser is the one enforcing.
- CSRF accepts only http and https, because it decides whether a request may mutate state and a non-web scheme has no business doing so.
This package decides only whether two serialized origins are the same string after normalization. It does not fold default ports, so "https://a.com" and "https://a.com:443" are different origins here. That is what an Origin header carries (RFC 6454 Section 6.1 serializes without the default port), and it is deliberately stricter than internal/schemehost, which folds ports because it compares URLs rather than origins.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func FromURL ¶ added in v3.7.0
FromURL serializes the origin of an already parsed URL as lowercase "scheme://host", dropping userinfo, path, query and fragment. It is the one place that spells an origin string, shared by Normalize and by callers that derive an origin from a full URL, such as the Referer check in CSRF.
Unlike Normalize it validates nothing: a URL with an empty host or a scheme outside the caller's policy still yields a string. That string is only safe to compare against an AllowList, whose entries are all valid origins, so an invalid one can match nothing there.
An IPv6 host is written as a browser serializes it, so "[0:0:0:0:0:0:0:1]" matches the "[::1]" an Origin header carries.
func MatchAny ¶
func MatchAny(subs []Subdomain, raw string, policy SchemePolicy) bool
MatchAny reports whether raw sits under any of the wildcards.
raw must already be in normalized form: it is normalized again and rejected if that changes it, so a request carrying "https://EXAMPLE.com" or a trailing slash cannot match a pattern that the same value in canonical form would not.
func Normalize ¶
func Normalize(raw string, policy SchemePolicy) (string, bool)
Normalize reports whether raw is a well formed origin and returns it as lowercase "scheme://host".
An origin is scheme and host and nothing else, so userinfo, a query, a fragment, or a path beyond a bare "/" all make it invalid rather than being stripped. A "*" anywhere in the host is rejected outright: a wildcard is only meaningful as a whole configured pattern, never inside a value, so "https://*" is not an origin (see the note on Access-Control-Allow-Origin in RFC 6454 Section 7.1).
Types ¶
type AllowList ¶ added in v3.7.0
type AllowList struct {
// contains filtered or unexported fields
}
AllowList is a parsed allow list, such as CORS AllowOrigins or CSRF TrustedOrigins: the exact origins, the subdomain wildcards, and the scheme policy both were parsed under. The zero value is an empty list.
func ParseAllowList ¶ added in v3.7.0
func ParseAllowList(entries []string, policy SchemePolicy) (allowList AllowList, invalid string, ok bool)
ParseAllowList parses every entry of a configured allow list with ParsePattern, after trimming the whitespace around it.
It stops at the first entry that does not parse and returns that entry as written, untrimmed, with ok false, so each middleware can name it in its own configuration error. The list is only built here, never per request.
func (AllowList) Contains ¶ added in v3.7.0
Contains reports whether o is on the list, either as an exact entry or under one of its wildcards.
o must be in normalized form, as Normalize or FromURL produce it; it is compared, not normalized. A value that is not normalized fails the exact lookup, and MatchAny rejects it for the wildcards.
type Pattern ¶
type Pattern struct {
// Subdomain is set when Wildcard, and zero otherwise.
Subdomain Subdomain
// Origin is the normalized value when not Wildcard, and empty otherwise.
Origin string
// Wildcard reports which of the two fields above carries the entry.
Wildcard bool
}
Pattern is one parsed entry of an allow list, which is either a plain origin or a subdomain wildcard.
func ParsePattern ¶
func ParsePattern(pattern string, policy SchemePolicy) (Pattern, bool)
ParsePattern reads one allow-list entry and reports whether it is usable.
An entry that does not normalize is rejected, so callers get one place to fail rather than one per shape.
type SchemePolicy ¶
type SchemePolicy uint8
SchemePolicy says which URL schemes a caller is willing to treat as an origin.
const ( // AnyScheme accepts whatever scheme url.Parse accepts. Used by CORS. AnyScheme SchemePolicy = iota // WebSchemesOnly accepts only http and https. Used by CSRF. WebSchemesOnly )