origin

README

Origin

Package origin provides simple tools and methods to compare and verify the Origin header of a request on the server-side, specifically in the context of Cross-Origin Resource Sharing (CORS).

It supports simple wildcard pattern-matching, and handles omitted port numbers for the most common web protocols.

Patterns

The patterns to be checked must be formatted as following:

scheme://hostname:port

A wildcard * is valid in any position, scheme, hostname or port (e.g. *://example.com:*).

port can be omitted if scheme is a common web protocol. The value will default to the standard port associated with it (e.g. 443 for HTTPS).

hostname can contain multiple wildcards to target subdomains. For example, *.*.example.com will match any sub-subdomain of example.com.

* is a valid pattern value, and is the equivalent of *://*:*.

Usage

Single pattern

import (
  "fmt"

  "github.com/posterity/origin"
)

func Main() {
  ok, err := origin.Match("https://subdomain.example.com:443", "https://*.example.com")
  if err != nil {
    panic(err) // Either the origin or the pattern is mis-formatted.
  }
  fmt.Println("is is a match? %v", ok)
}

List of patterns

import (
  "io"

  "github.com/posterity/origin"
)

var patterns = origin.Patterns{
  "https://example.com",
  "https://*.example.com",
  "*://localhost:*",
}

func handler(w http.ResponseWriter, r *http.Request) {
  ok, err := patterns.Match(origin.Get(r))
  if err != nil {
    panic(err) // Either the origin or the pattern is mis-formatted.
  }
  if !ok {
    w.WriteHeader(401)
    io.WriteString(w, "This request is not from a trusted origin")
    return
  }

  io.WriteString(w, "Hello, World!")
}

Contributions

Contributions are welcome via Pull Requests.

About us

What if you're hit by a bus tomorrow? Posterity helps you make a plan in the event something happens to you.

Documentation

Overview

Package origin implements tools and methods to compare and perform simple pattern-matching on the origin header of a request on the server-side, specifically in the context of cross-origin resource sharing (CORS).

Index

• func Get(r *http.Request) string
• func Match(origin, pattern string) (bool, error)
• func Split(origin string) (scheme, host, port string, err error)
• type Patterns
  • func (p Patterns) Match(origin string) (bool, error)

Functions

func Get

func Get(r *http.Request) string

Get returns the value of the origin header in r.

An empty string is returned if the value in the header is "null", indicating an opaque origin.

func Match

func Match(origin, pattern string) (bool, error)

Match returns true if the scheme, hostname and port of origin match the ones in the given pattern.

Both the origin and the pattern must be formatted as:

scheme://hostname:port

Pattern may contain a wildcard "*" in any of the three components. For example, "https://*.example.com:*" will consider any subdomain of "example.com" on any port number as a match, provided that the scheme is HTTPS.

The port number may be omitted in either the origin or pattern when the scheme has a known standard port number. For example, "https://example.com" and "https://example.com:443" are a match.

The special pattern value "*" is equivalent to "*://*:*", and matches with any non-empty and valid origin.

func Split

func Split(origin string) (scheme, host, port string, err error)

Split is similar to net.SplitHostPort, but accounts for the scheme (protocol), and returns the implicit corresponding port if origin doesn't explicitly mention one. For example, "https://example.com" will return "https", "example.com" and "443" as the port.

Types

type Patterns

type Patterns []string

Patterns holds a list of trusted origins or patterns against which an origin header can be checked.

Valid values are well-formed URLs, or patterns formatted as specified in the Match function.

func (Patterns) Match

func (p Patterns) Match(origin string) (bool, error)

Match returns true if any of the patterns in p matches with origin.