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. |