par

Documentation

Overview

Package par implements the shared wire format for Pushed Authorization Requests (RFC 9126): request encoding, the request_uri response shape, and the parameter rules common to submitting and accepting a PAR request.

client uses this to submit a PAR request and interpret the request_uri/expires_in response; server uses it to parse and validate an inbound PAR submission. Client-authentication verification and request-object verification are out of scope here — see internal/clientassertion and internal/requestobject.

Index

• Constants
• Variables
• func DecodeForm(body []byte) (map[string]string, error)
• func EncodeErrorResponse(e ErrorResponse) ([]byte, error)
• func EncodeForm(params map[string]string) []byte
• func EncodeResult(r PushResult) ([]byte, error)
• func GenerateRequestURI(random io.Reader) (string, error)
• func SplitRequestURI(requestURI string) (reference string, ok bool)
• type ErrorResponse
  • func DecodeErrorResponse(body []byte) (ErrorResponse, error)
• type PushResult
  • func DecodeResult(body []byte) (PushResult, error)

Constants

const RequestURIPrefix = "urn:ietf:params:oauth:request_uri:"

RequestURIPrefix is the URN prefix this package uses when generating a request_uri value, following the example construction in RFC 9126 §2.2. The wire format of a request_uri is at the discretion of the authorization server that issues it — a client verifying a response from a third-party server must not assume this prefix (see DecodeResult) — but a server built on this package uses it consistently so it can recognize its own values without a store lookup.

Variables

var (
	// ErrFormTooLarge indicates a form-encoded body larger than this
	// package is willing to parse.
	ErrFormTooLarge = errors.New("par: form body exceeds maximum size")

	// ErrResponseTooLarge indicates a JSON response body larger than
	// this package is willing to parse.
	ErrResponseTooLarge = errors.New("par: response body exceeds maximum size")

	// ErrMalformedForm indicates a form-encoded body that could not be
	// parsed as application/x-www-form-urlencoded.
	ErrMalformedForm = errors.New("par: malformed form body")

	// ErrDuplicateParameter indicates a form-encoded body containing the
	// same parameter name more than once. A PAR submission (or any
	// OAuth request body) with a duplicate parameter is rejected rather
	// than resolved by picking the first or last occurrence, since
	// either choice can be turned into a request-smuggling primitive.
	ErrDuplicateParameter = errors.New("par: duplicate parameter")

	// ErrMalformedResponse indicates a PAR response body that was not
	// valid JSON, or was missing a required field, or had a field of
	// the wrong shape.
	ErrMalformedResponse = errors.New("par: malformed response")

	// ErrMissingRequestURI indicates a PAR success response with an
	// empty or absent request_uri.
	ErrMissingRequestURI = errors.New("par: response is missing request_uri")

	// ErrInvalidExpiresIn indicates a PAR success response whose
	// expires_in is not a positive number of seconds.
	ErrInvalidExpiresIn = errors.New("par: expires_in must be positive")

	// ErrMissingErrorCode indicates an OAuth error response body with an
	// empty or absent error code.
	ErrMissingErrorCode = errors.New("par: error response is missing error code")
)

Functions

func DecodeForm

func DecodeForm(body []byte) (map[string]string, error)

DecodeForm parses an application/x-www-form-urlencoded body into a single-valued parameter map. It rejects a body larger than this package is willing to parse, and rejects any parameter name that appears more than once — resolving a duplicate by picking the first or last occurrence would let it be used as a request-smuggling primitive, so this package refuses to guess.

func EncodeErrorResponse

func EncodeErrorResponse(e ErrorResponse) ([]byte, error)

EncodeErrorResponse builds the JSON body of an OAuth error response.

func EncodeForm

func EncodeForm(params map[string]string) []byte

EncodeForm builds a deterministic application/x-www-form-urlencoded body from params. Key order in the output is sorted, not caller-controlled, since url.Values.Encode does the sorting.

func EncodeResult

func EncodeResult(r PushResult) ([]byte, error)

EncodeResult builds the JSON body of a successful PAR response.

func GenerateRequestURI

func GenerateRequestURI(random io.Reader) (string, error)

GenerateRequestURI produces a new, random request_uri value. If random is nil, crypto/rand.Reader is used.

func SplitRequestURI

func SplitRequestURI(requestURI string) (reference string, ok bool)

SplitRequestURI reports whether requestURI has the form this package generates and, if so, returns its reference component — the part a server can use as a lookup key into its transaction store without storing the prefix redundantly. It returns ok == false for any value that doesn't have RequestURIPrefix, which a server can use as a fast rejection before attempting a store lookup at all.

Types

type ErrorResponse

type ErrorResponse struct {
	Code        string
	Description string // optional
	URI         string // optional
}

ErrorResponse is a standard OAuth error response (RFC 6749 §5.2), used for a PAR endpoint's error responses.

func DecodeErrorResponse

func DecodeErrorResponse(body []byte) (ErrorResponse, error)

DecodeErrorResponse parses the JSON body of an OAuth error response. A member beyond error/error_description/error_uri is tolerated, not rejected — RFC 6749 §5.2 defines this same closed set of fields but, like §5.1's success response, doesn't make an unrecognized extra one a reason to fail parsing the response at all.

type PushResult

type PushResult struct {
	RequestURI string
	ExpiresIn  time.Duration
}

PushResult is a successful PAR response (RFC 9126 §2.2).

func DecodeResult

func DecodeResult(body []byte) (PushResult, error)

DecodeResult parses the JSON body of a successful PAR response. It does not assume RequestURIPrefix — a third-party authorization server may use any opaque format for request_uri — and only requires that the value be present and that expires_in be a positive number of seconds. A member beyond request_uri/expires_in is tolerated, not rejected: RFC 9126 itself doesn't say so explicitly (it only ever defines request_uri/expires_in, with no extensibility clause either way), but rejecting a structurally-valid response just because a server added a field is the wrong default for a JSON API response — the same reasoning RFC 6749 §5.1 states outright for the token response.