Skip to content

Latest commit

 

History

History
234 lines (175 loc) · 9.95 KB

README.md

File metadata and controls

234 lines (175 loc) · 9.95 KB
Raw

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