httpbakery

func AddDischargeHandler ¶

func AddDischargeHandler(mux *http.ServeMux, rootPath string, svc *bakery.Service, checker func(req *http.Request, cavId, cav string) ([]checkers.Caveat, error))

AddDischargeHandler adds handlers to the given ServeMux to serve third party caveat discharges using the given service.

The handlers are added under the given rootPath, which must be non-empty.

The check function is used to check whether a client making the given request should be allowed a discharge for the given caveat. If it does not return an error, the caveat will be discharged, with any returned caveats also added to the discharge macaroon. If it returns an error with a *Error cause, the error will be marshaled and sent back to the client.

The name space served by DischargeHandler is as follows. All parameters can be provided either as URL attributes or form attributes. The result is always formatted as a JSON object.

On failure, all endpoints return an error described by the Error type.

POST /discharge

params:
	id: id of macaroon to discharge
	location: location of original macaroon (optional (?))
	?? flow=redirect|newwindow
result on success (http.StatusOK):
	{
		Macaroon *macaroon.Macaroon
	}

POST /create

params:
	condition: caveat condition to discharge
	rootkey: root key of discharge caveat
result:
	{
		CaveatID: string
	}

GET /publickey

result:
	public key of service
	expiry time of key

func CheckRequest ¶

func CheckRequest(svc *bakery.Service, req *http.Request, assert map[string]string, checker checkers.Checker) (map[string]string, error)

CheckRequest checks that the given http request contains at least one valid macaroon minted by the given service, using checker to check any first party caveats. It returns an error with a *bakery.VerificationError cause if the macaroon verification failed.

The assert map holds any required attributes of "declared" attributes, overriding any inferences made from the macaroons themselves. It has a similar effect to adding a checkers.DeclaredCaveat for each key and value, but the error message will be more useful.

It adds all the standard caveat checkers to the given checker.

It returns any attributes declared in the successfully validated request.

func Checkers ¶

func Checkers(req *http.Request) checkers.Checker

Checkers implements the standard HTTP-request checkers. It does not include the "declared" checker, as that must be added for each individual set of macaroons that are checked.

func DischargeAll ¶

func DischargeAll(m *macaroon.Macaroon, client *http.Client, visitWebPage func(url *url.URL) error) (macaroon.Slice, error)

DischargeAll attempts to acquire discharge macaroons for all the third party caveats in m, and returns a slice containing all of them bound to m.

If the discharge fails because a third party refuses to discharge a caveat, the returned error will have a cause of type *DischargeError. If the discharge fails because visitWebPage returns an error, the returned error will have a cause of *InteractionError.

The returned macaroon slice will not be stored in the client cookie jar (see SetCookie if you need to do that).

func Do ¶

func Do(client *http.Client, req *http.Request, visitWebPage func(url *url.URL) error) (*http.Response, error)

Do makes an http request to the given client. If the request fails with a discharge-required error, any required discharge macaroons will be acquired, and the request will be repeated with those attached.

If the required discharges were refused by a third party, an error with a *DischargeError cause will be returned.

Note that because the request may be retried, no body may be provided in the http request (otherwise the contents will be lost when retrying). For requests with a body (for example PUT or POST methods), use DoWithBody instead.

If the client.Jar field is non-nil, the macaroons will be stored there and made available to subsequent requests.

If interaction is required by the user, the visitWebPage function is called with a URL to be opened in a web browser. If visitWebPage returns an error, an error with a *InteractionError cause will be returned. See OpenWebBrowser for a possible implementation of visitWebPage.

func DoWithBody ¶

func DoWithBody(client *http.Client, req *http.Request, getBody BodyGetter, visitWebPage func(url *url.URL) error) (*http.Response, error)

DoWithBody is like Do except that the given getBody function is called to obtain the body for the HTTP request. Any returned body will be closed after each request is made.

func ErrorToResponse ¶

func ErrorToResponse(err error) (int, interface{})

ErrorToResponse returns the HTTP status and an error body to be marshaled as JSON for the given error. This allows a third party package to integrate bakery errors into their error responses when they encounter an error with a *bakery.Error cause.

func IsDischargeError ¶

func IsDischargeError(err error) bool

IsDischargeError reports whether err is a *DischargeError.

func IsInteractionError ¶

func IsInteractionError(err error) bool

IsInteractionError reports whether err is a *DischargeError.

func NewCookie ¶

func NewCookie(ms macaroon.Slice) (*http.Cookie, error)

NewCookie takes a slice of macaroons and returns them encoded as a cookie. The slice should contain a single primary macaroon in its first element, and any discharges after that.

func NewDischargeRequiredError ¶

func NewDischargeRequiredError(m *macaroon.Macaroon, path string, originalErr error) error

NewDischargeRequiredError returns an error of type *Error that reports the given original error and includes the given macaroon.

The returned macaroon will be declared as valid for the given URL path and may be relative. When the client stores the discharged macaroon as a cookie this will be the path associated with the cookie. See ErrorInfo.MacaroonPath for more information.

func NewHTTPClient ¶

func NewHTTPClient() *http.Client

NewHTTPClient returns an http.Client that ensures that headers are sent to the server even when the server redirects a GET request. The returned client also contains an empty in-memory cookie jar.

See https://github.com/golang/go/issues/4677

func OpenWebBrowser ¶

func OpenWebBrowser(url *url.URL) error

OpenWebBrowser opens a web browser at the given URL. If the OS is not recognised, the URL is just printed to standard output.

func PublicKeyForLocation ¶

func PublicKeyForLocation(client *http.Client, url string) (*bakery.PublicKey, error)

PublicKeyForLocation returns the public key from a macaroon discharge server running at the given location URL. Note that this is insecure if an http: URL scheme is used.

func RequestMacaroons ¶

func RequestMacaroons(req *http.Request) []macaroon.Slice

RequestMacaroons returns any collections of macaroons from the cookies found in the request. By convention, each slice will contain a primary macaroon followed by its discharges.

func SameClientIPAddrCaveat ¶

func SameClientIPAddrCaveat(req *http.Request) checkers.Caveat

SameClientIPAddrCaveat returns a caveat that will check that the remote IP address is the same as that in the given HTTP request.

func SetCookie ¶

func SetCookie(jar http.CookieJar, url *url.URL, ms macaroon.Slice) error

SetCookie sets a cookie for the given URL on the given cookie jar that will holds the given macaroon slice. The macaroon slice should contain a single primary macaroon in its first element, and any discharges after that.

func WriteDischargeRequiredError ¶

func WriteDischargeRequiredError(w http.ResponseWriter, m *macaroon.Macaroon, path string, originalErr error)

WriteDischargeRequiredError creates an error using NewDischargeRequiredError and writes it to the given response writer, indicating that the client should discharge the macaroon to allow the original request to be accepted.