norm

README

norm

The code.soquee.net/norm module is a Go package used normalizing HTTP forms using the PRECIS (preparation, enforcement, and comparison of internationalized strings) framework defined in RFC8264.

import (
	"code.soquee.net/norm"
)

License

The package may be used under the terms of the BSD 2-Clause License a copy of which may be found in the LICENSE file.

Unless you explicitly state otherwise, any contribution submitted for inclusion in the work by you shall be licensed as above, without any additional terms or conditions.

Documentation

Overview

Package norm contains middleware for normalizing forms in HTTP requests.

In particular this package is useful for normalizing forms submitted with HTTP requests using the PRECIS (preparation, enforcement, and comparison of internationalized strings) security framework.

Custom normalization rules may also be applied eg. to normalize using the legacy STRINGPREP algorithm or perform other validations.

Index

• Constants
• Variables
• func NormalizeEmail(email string) (string, error)
• func NormalizeForm(r *http.Request, opts ...Option) (badkey string, err error)
• func Username(displayname string) (string, error)
• type Option
  • func DisplayName(key string) Option
  • func Email(key string) Option
  • func Name(key string) Option
  • func OpaqueString(key string) Option
  • func Password(key string) Option
  • func UnixLineEndings(key string) Option

Constants

const (
	MinPasswordLength = 12
	MaxPasswordLength = 1000
)

Constants used for validating passwords.

const Disallowed = `:/\?#[]@!#&'()*+,;=.%`

Disallowed are extra characters that are not allowed by URLProfile. They are mostly taken from RFC 3986 §2.2 except for '.' and '%' which are reserved by us.

const UnicodeVersion = precis.UnicodeVersion

UnicodeVersion is the Unicode version from which the tables used by this package are derived.

Variables

var (
	ErrLongPassword  = errors.New("norm: password is too long")
	ErrShortPassword = errors.New("norm: password is too short")
)

Errors that may be returned by validation functions in this package.

var URLProfile = precis.NewRestrictedProfile(precis.UsernameCaseMapped,
	runes.Predicate(func(r rune) bool {
		return strings.ContainsRune(Disallowed, r)
	}),
)

URLProfile is a version of the Username Case Mapped profile with additional restricted characters. It is useful for usernames that are used for login (not for display names that are shown to users) and other unique names in particular. This is not one of the standard PRECIS profiles and it may not be suitable for all projects.

See Disallowed for a list of restricted characters.

Functions

func NormalizeEmail

func NormalizeEmail(email string) (string, error)

NormalizeEmail returns the canonical form of the given email if available. It accepts addresses of the form "Name <email>" where the name and angle brackets are optional.

func NormalizeForm

func NormalizeForm(r *http.Request, opts ...Option) (badkey string, err error)

NormalizeForm calls ParseForm on the request and then attempts to normalize the provided form values. It does not attempt to normalize multipart form data or URL query parameters.

If an error is returned then badkey will be the form field name that triggered the error.

func Username

func Username(displayname string) (string, error)

Username returns a username from the given displayname by removing spaces and applying URLProfile.

Types

type Option

type Option func(getsetter) (string, error)

Option configures form normalization.

func DisplayName

func DisplayName(key string) Option

DisplayName is an Option that normalizes a form parmeter using the Username Case Preserved PRECIS profile on each individual word ("userpart" in PRECIS lingo) in the name and normalizing spaces to ASCII Space.

func Email

func Email(key string) Option

Email is an Option that validates and normalizes an email using NormalizeEmail.

func Name

func Name(key string) Option

Name is an Option that normalizes a form parameter using URLProfile.

func OpaqueString

func OpaqueString(key string) Option

OpaqueString is a normalizer that applies the precise OpaqueString profile.

While OpaqueString is mostly applied to passwords, the Password option provides other validations and should generally be used instead.

func Password

func Password(key string) Option

Password is a normalizer that applies the precise OpaqueString profile and checks password length limits (see MinPasswordLength and MaxPasswordLength).

This is mostly used for passwords, but may also be useful for normalizing any generic string where flexibility is required but where basic constraints (eg. the string may not be empty) are still desirable.

func UnixLineEndings

func UnixLineEndings(key string) Option

UnixLineEndings normalizes "\r\n" and "\r" to "\n".