macaroon

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

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.