@canonical/macaroon-bakery

bakeryjs

API Reference

bakeryjs.

Example

import { Bakery } from "@canonical/macaroon-bakery";
const bakery = new Bakery();

bakery.get(url, headers, callback);

• bakeryjs
  • ~Bakery
    • new Bakery(config)
    • .sendRequest(url, method, headers, body, callback) ⇒ Object
    • .get()
    • .delete()
    • .post()
    • .put()
    • .patch()
    • .discharge(macaroon, onSuccess, onFailure)
  • ~BakeryStorage
    • new BakeryStorage(store, config)
    • .get(key) ⇒ String
    • .set(key, value, callback)
    • .clear()
  • ~InMemoryStore
  • ~serialize(macaroons) ⇒ string
  • ~deserialize(serialized) ⇒ Array

bakeryjs~Bakery

A macaroon bakery implementation.

The bakery implements the protocol used to acquire and discharge macaroons over HTTP.

Kind: inner class of bakeryjs

• ~Bakery
  • new Bakery(config)
  • .sendRequest(url, method, headers, body, callback) ⇒ Object
  • .get()
  • .delete()
  • .post()
  • .put()
  • .patch()
  • .discharge(macaroon, onSuccess, onFailure)

new Bakery(config)

Initialize a macaroon bakery with the given parameters.

Param	Type	Description
config	Object	optional config.
config.onSuccess	function	a function to be called when the request completes properly.
config.protocolVersion	number	the macaroon protocol version that the bakery should use.
config.storage	function	the storage used to persist macaroons. It must implement the following interface:
config.storage.get	function	get(key) -> value.
config.storage.set	function	set(key, value, callback): the callback is called without arguments when the set operation has been performed. If not provided, it defaults to BakeryStorage using an in memory store.
config.visitPage	function	the function used to visit the identity provider page when required, defaulting to opening a pop up window. It receives an error object.
config.visitPage.Info	Object	an object containing relevant info for the visit handling.
config.visitPage.Info.WaitUrl	String	the url to wait on for IdM discharge.
config.visitPage.Info.VisitUrl	String	the url to visit to authenticate with the IdM.
config.visitPage.jujugui	function	an optional value specifying a method to use against idm to authenticate. Used in non interactive authentication scenarios.
config.sendRequest	function	a function used to make XHR HTTP requests, with the following signature: func(path, method, headers, body, withCredentials, callback) -> xhr. By default an internal function is used. This is mostly for testing.

bakery.sendRequest(url, method, headers, body, callback) ⇒ Object

Send an HTTP request to the given URL with the given HTTP method, headers and body. The given callback receives an error and a response when the request is complete.

Kind: instance method of Bakery
Returns: Object - the XHR instance.

Param	Type	Description
url	String	The URL to which to send the request.
method	String	The HTTP method, like "get" or "POST".
headers	Object	Headers that must be included in the request. Note that bakery specific headers are automatically added internally.
body	String	The request body if it applies, or null.
callback	function	A function called when the response is received from the remote URL. It receives a tuple (error, response). If the request succeeds the error is null.

bakery.get()

Send an HTTP GET request to the given URL with the given headers. The given callback receives an error and a response when the request is complete.

See the "sendRequest" method above for a description of the parameters.

Kind: instance method of Bakery

bakery.delete()

Send an HTTP DELETE request to the given URL with the given headers and body. The given callback receives an error and a response when the request is complete.

See the "sendRequest" method above for a description of the parameters.

Kind: instance method of Bakery

bakery.post()

Send an HTTP POST request to the given URL with the given headers and body. The given callback receives an error and a response when the request is complete.

See the "sendRequest" method above for a description of the parameters.

Kind: instance method of Bakery

bakery.put()

Send an HTTP PUT request to the given URL with the given headers and body. The given callback receives an error and a response when the request is complete.

See the "sendRequest" method above for a description of the parameters.

Kind: instance method of Bakery

bakery.patch()

Send an HTTP PATCH request to the given URL with the given headers and body. The given callback receives an error and a response when the request is complete.

See the "sendRequest" method above for a description of the parameters.

Kind: instance method of Bakery

bakery.discharge(macaroon, onSuccess, onFailure)

Discharge the given macaroon. Acquire any third party discharges.

Kind: instance method of Bakery

Param	Type	Description
macaroon	Object	The decoded macaroon to be discharged.
onSuccess	function	The function to be called if the discharge succeeds. It receives the resulting macaroons array.
onFailure	function	The function to be called if the discharge fails. It receives an error message.

bakeryjs~BakeryStorage

A storage for the macaroon bakery.

The storage is used to persist macaroons.

Kind: inner class of bakeryjs

• ~BakeryStorage
  • new BakeryStorage(store, config)
  • .get(key) ⇒ String
  • .set(key, value, callback)
  • .clear()

new BakeryStorage(store, config)

Initialize a bakery storage with the given underlaying store and params.

Param	Type	Description
store	Object	A store object implement the following interface: - getItem(key) -> value; - setItem(key, value); - clear().
config	Object	Optional configuration.
config.initial	Object	a map of key/value pairs that must be initially included in
config.services	Object	a map of service names (like "charmstore" or "terms") to the base URL of their corresponding API endpoints. This is used to simplify and reduce the URLs passed as keys to the storage.
config.charmstoreCookieSetter	function	a function that can be used to register macaroons to the charm store service. The function accepts a value and a callback, which receives an error and a response.

bakeryStorage.get(key) ⇒ String

Retrieve and return the value for the provided key.

Kind: instance method of BakeryStorage
Returns: String - The corresponding value, usually a serialized macaroon.

Param	Type	Description
key	String	The storage key, usually a URL.

bakeryStorage.set(key, value, callback)

Store the given value in the given storage key.

Call the callback when done.

Kind: instance method of BakeryStorage

Param	Type	Description
key	String	The storage key, usually a URL.
value	String	The value, usually a serialized macaroon.
callback	function	A function called without arguments when the value is properly stored.

bakeryStorage.clear()

Remove all key/value pairs from the storage.

Kind: instance method of BakeryStorage

bakeryjs~InMemoryStore

An in-memory store for the BakeryStorage.

Kind: inner class of bakeryjs

bakeryjs~serialize(macaroons) ⇒ string

Serialize the given macaroons.

Kind: inner method of bakeryjs
Returns: string - The resulting serialized string.

Param	Type	Description
macaroons	Array	The macaroons to be serialized.

bakeryjs~deserialize(serialized) ⇒ Array

De-serialize the given serialized macaroons.

Kind: inner method of bakeryjs
Returns: Array - The resulting macaroon slice.

Param	Type	Description
serialized	string	The serialized macaroons.

---