macaroon

A JavaScript implementation of macaroons compatible with the Go, Python, and C implementations. Including functionality to interact with third party caveat dischargers implemented by the Go macaroon bakery. It supports both version 1 and 2 macaroons in JSON and binary formats.

• macaroon
  • Macaroon#caveats ⇒ Array ⏏
  • Macaroon#location ⇒ string ⏏
  • Macaroon#identifier ⇒ Uint8Array ⏏
  • Macaroon#signature ⇒ Uint8Array ⏏
  • base64ToBytes(s) ⇒ Uint8Array ⏏
  • bytesToBase64(bytes) ⇒ string ⏏
  • Macaroon#addThirdPartyCaveat(rootKeyBytes, caveatIdBytes, [locationStr]) ⏏
  • Macaroon#addFirstPartyCaveat(caveatIdBytes) ⏏
  • Macaroon#bindToRoot(rootSig) ⏏
  • Macaroon#clone() ⇒ Macaroon ⏏
  • Macaroon#verify(rootKeyBytes, check, discharges) ⏏
  • Macaroon#exportJSON() ⇒ Object ⏏
  • Macaroon#exportBinary() ⇒ Uint8Array ⏏
  • importMacaroon(obj) ⇒ Macaroon | Array.<Macaroon> ⏏
  • importMacaroons(obj) ⇒ Array.<Macaroon> ⏏
  • newMacaroon() ⇒ Macaroon ⏏
  • dischargeMacaroon(macaroon, getDischarge, onOk, onError) ⏏

Macaroon#caveats ⇒ Array ⏏

Return the caveats associated with the macaroon, as an array of caveats. A caveat is represented as an object with an identifier field (Uint8Array) and (for third party caveats) a location field (string), and verification id (Uint8Array).

Kind: Exported member
Returns: Array - - The macaroon's caveats.

Macaroon#location ⇒ string ⏏

Return the location of the macaroon.

Kind: Exported member
Returns: string - - The macaroon's location.

Macaroon#identifier ⇒ Uint8Array ⏏

Return the macaroon's identifier.

Kind: Exported member
Returns: Uint8Array - - The macaroon's identifier.

Macaroon#signature ⇒ Uint8Array ⏏

Return the signature of the macaroon.

Kind: Exported member
Returns: Uint8Array - - The macaroon's signature.

base64ToBytes(s) ⇒ Uint8Array ⏏

Convert a base64 string to a Uint8Array by decoding it. It copes with unpadded and URL-safe base64 encodings.

Kind: Exported function
Returns: Uint8Array - - The decoded bytes.

| Param | Type | Description | | --- | --- | --- | | s | string | The base64 string to decode. |

bytesToBase64(bytes) ⇒ string ⏏

Convert a Uint8Array to a base64-encoded string using URL-safe, unpadded encoding.

Kind: Exported function
Returns: string - - The base64-encoded result.

| Param | Type | Description | | --- | --- | --- | | bytes | Uint8Array | The bytes to encode. |

Macaroon#addThirdPartyCaveat(rootKeyBytes, caveatIdBytes, [locationStr]) ⏏

Adds a third party caveat to the macaroon. Using the given shared root key, caveat id and location hint. The caveat id should encode the root key in some way, either by encrypting it with a key known to the third party or by holding a reference to it stored in the third party's storage.

Kind: Exported function

| Param | Type | | --- | --- | | rootKeyBytes | Uint8Array | | caveatIdBytes | Uint8Array | string | | [locationStr] | String |

Macaroon#addFirstPartyCaveat(caveatIdBytes) ⏏

Adds a caveat that will be verified by the target service.

Kind: Exported function

| Param | Type | | --- | --- | | caveatIdBytes | String | Uint8Array |

Macaroon#bindToRoot(rootSig) ⏏

Binds the macaroon signature to the given root signature. This must be called on discharge macaroons with the primary macaroon's signature before sending the macaroons in a request.

Kind: Exported function

| Param | Type | | --- | --- | | rootSig | Uint8Array |

Macaroon#clone() ⇒ Macaroon ⏏

Returns a copy of the macaroon. Any caveats added to the returned macaroon will not effect the original.

Kind: Exported function
Returns: Macaroon - - The cloned macaroon.

Macaroon#verify(rootKeyBytes, check, discharges) ⏏

Verifies that the macaroon is valid. Throws exception if verification fails.

Kind: Exported function

| Param | Type | Description | | --- | --- | --- | | rootKeyBytes | Uint8Array | Must be the same that the macaroon was originally created with. | | check | function | Called to verify each first-party caveat. It is passed the condition to check (a string) and should return an error string if the condition is not met, or null if satisfied. | | discharges | Array | |

Macaroon#exportJSON() ⇒ Object ⏏

Exports the macaroon to a JSON-serializable object. The version used depends on what version the macaroon was created with or imported from.

Kind: Exported function

Macaroon#exportBinary() ⇒ Uint8Array ⏏

Exports the macaroon using binary format. The version will be the same as the version that the macaroon was created with or imported from.

Kind: Exported function

importMacaroon(obj) ⇒ Macaroon | Array.<Macaroon> ⏏

Returns a macaroon instance based on the object passed in. If obj is a string, it is assumed to be a base64-encoded macaroon in binary or JSON format. If obj is a Uint8Array, it is assumed to be a macaroon in binary format, as produced by the exportBinary method. Otherwise obj is assumed to be a object decoded from JSON, and will be unmarshaled as such.

Kind: Exported function

| Param | Description | | --- | --- | | obj | A deserialized JSON macaroon. |

importMacaroons(obj) ⇒ Array.<Macaroon> ⏏

Returns an array of macaroon instances based on the object passed in. If obj is a string, it is assumed to be a set of base64-encoded macaroons in binary or JSON format. If obj is a Uint8Array, it is assumed to be set of macaroons in binary format, as produced by the exportBinary method. If obj is an array, it is assumed to be an array of macaroon objects decoded from JSON. Otherwise obj is assumed to be a macaroon object decoded from JSON.

This function accepts a strict superset of the formats accepted by importMacaroons. When decoding a single macaroon, it will return an array with one macaroon element.

Kind: Exported function

| Param | Description | | --- | --- | | obj | A deserialized JSON macaroon or macaroons. |

newMacaroon() ⇒ Macaroon ⏏

Create a new Macaroon with the given root key, identifier, location and signature and return it.

Kind: Exported function

| Type | Description | | --- | --- | | Object | The necessary values to generate a macaroon. It contains the following fields: identifier: {String | Uint8Array} location: {String} (optional) rootKey: {String | Uint8Array} version: {int} (optional; defaults to 2). |

dischargeMacaroon(macaroon, getDischarge, onOk, onError) ⏏

Gathers discharge macaroons for all third party caveats in the supplied macaroon (and any subsequent caveats required by those) calling getDischarge to acquire each discharge macaroon.

Kind: Exported function

| Param | Type | Description | | --- | --- | --- | | macaroon | Macaroon | The macaroon to discharge. | | getDischarge | function | Called with 5 arguments. macaroon.location {String} caveat.location {String} caveat.id {String} success {Function} failure {Function} | | onOk | function | Called with an array argument holding the macaroon as the first element followed by all the discharge macaroons. All the discharge macaroons will be bound to the primary macaroon. | | onError | function | Called if an error occurs during discharge. |