blockstack
Version:
The Blockstack Javascript library for identity and authentication.
1,967 lines (867 loc) • 60.6 kB
HTML
<!doctype html>
<html>
<head>
<meta charset='utf-8' />
<title>blockstack 0.15.0 | Documentation</title>
<meta name='viewport' content='width=device-width,initial-scale=1'>
<link href='assets/bass.css' type='text/css' rel='stylesheet' />
<link href='assets/style.css' type='text/css' rel='stylesheet' />
<link href='assets/github.css' type='text/css' rel='stylesheet' />
</head>
<body class='documentation'>
<div class='max-width-4 mx-auto'>
<div class='clearfix md-mxn2'>
<div class='fixed xs-hide fix-3 overflow-auto max-height-100'>
<div class='py1 px2'>
<h3 class='mb0 no-anchor'>blockstack</h3>
<div class='mb1'><code>0.15.0</code></div>
<input
placeholder='Filter'
id='filter-input'
class='col12 block input'
type='text' />
<div id='toc'>
<ul class='list-reset h5 py1-ul'>
<li><a
href='#authentication'
class="h5 bold black caps">
Authentication
</a>
</li>
<li><a
href='#redirecttosignin'
class="">
redirectToSignIn
</a>
</li>
<li><a
href='#issigninpending'
class="">
isSignInPending
</a>
</li>
<li><a
href='#handlependingsignin'
class="">
handlePendingSignIn
</a>
</li>
<li><a
href='#loaduserdata'
class="">
loadUserData
</a>
</li>
<li><a
href='#isusersignedin'
class="">
isUserSignedIn
</a>
</li>
<li><a
href='#signuserout'
class="">
signUserOut
</a>
</li>
<li><a
href='#makeauthrequest'
class="">
makeAuthRequest
</a>
</li>
<li><a
href='#redirecttosigninwithauthrequest'
class="">
redirectToSignInWithAuthRequest
</a>
</li>
<li><a
href='#getauthresponsetoken'
class="">
getAuthResponseToken
</a>
</li>
<li><a
href='#profiles'
class="h5 bold black caps">
Profiles
</a>
</li>
<li><a
href='#extractprofile'
class="">
extractProfile
</a>
</li>
<li><a
href='#wrapprofiletoken'
class="">
wrapProfileToken
</a>
</li>
<li><a
href='#signprofiletoken'
class="">
signProfileToken
</a>
</li>
<li><a
href='#verifyprofiletoken'
class="">
verifyProfileToken
</a>
</li>
<li><a
href='#validateproofs'
class="">
validateProofs
</a>
</li>
<li><a
href='#lookupprofile'
class="">
lookupProfile
</a>
</li>
<li><a
href='#storage'
class="h5 bold black caps">
Storage
</a>
</li>
<li><a
href='#getfile'
class="">
getFile
</a>
</li>
<li><a
href='#putfile'
class="">
putFile
</a>
</li>
<li><a
href='#getappbucketurl'
class="">
getAppBucketUrl
</a>
</li>
<li><a
href='#getuserappfileurl'
class="">
getUserAppFileUrl
</a>
</li>
<li><a
href='#verifyauthresponse'
class="">
verifyAuthResponse
</a>
</li>
<li><a
href='#encryptecies'
class="">
encryptECIES
</a>
</li>
<li><a
href='#decryptecies'
class="">
decryptECIES
</a>
</li>
<li><a
href='#setlocalgaiahubconnection'
class="">
setLocalGaiaHubConnection
</a>
</li>
<li><a
href='#deletefile'
class="">
deleteFile
</a>
</li>
<li><a
href='#islaterversion'
class="">
isLaterVersion
</a>
</li>
</ul>
</div>
<div class='mt1 h6 quiet'>
<a href='http://documentation.js.org/reading-documentation.html'>Need help reading this?</a>
</div>
</div>
</div>
<div class='fix-margin-3'>
<div class='keyline-top-not py2'><section class='py2 clearfix'>
<h2 id='authentication' class='mt0'>
Authentication
</h2>
<p>Single sign on and authentication without third parties or remote servers.</p>
<p><a href="https://github.com/blockstack/blockstack.js/blob/master/src/auth/README.md">Read more about authentication</a></p>
</section>
</div>
<section class='p2 mb2 clearfix bg-white minishadow'>
<div class='clearfix'>
<h3 class='fl m0' id='redirecttosignin'>
redirectToSignIn
</h3>
</div>
<p>Generates an authentication request and redirects the user to the Blockstack
browser to approve the sign in request.</p>
<p>Please note that this requires that the web browser properly handles the
<code>blockstack:</code> URL protocol handler.</p>
<p>Most applications should use this
method for sign in unless they require more fine grained control over how the
authentication request is generated. If your app falls into this category,
use <code>generateAndStoreTransitKey</code>, <code>makeAuthRequest</code>,
and <code>redirectToSignInWithAuthRequest</code> to build your own sign in process.</p>
<div class='pre p1 fill-light mt0'>redirectToSignIn(redirectURI: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>, manifestURI: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>, scopes: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array">Array</a>): void</div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>redirectURI</span> <code class='quiet'>(<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>
= <code>`${window.location.origin}/`</code>)</code>
The location to which the identity provider will redirect the user after
the user approves sign in.
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>manifestURI</span> <code class='quiet'>(<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>
= <code>`${window.location.origin}/manifest.json`</code>)</code>
Location of the manifest file.
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>scopes</span> <code class='quiet'>(<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array">Array</a>
= <code>DEFAULT_SCOPE</code>)</code>
Defaults to requesting write access to
this app's data store.
An array of strings indicating which permissions this app is requesting.
</div>
</div>
</div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code>void</code>:
</section>
<section class='p2 mb2 clearfix bg-white minishadow'>
<div class='clearfix'>
<h3 class='fl m0' id='issigninpending'>
isSignInPending
</h3>
</div>
<p>Check if there is a authentication request that hasn't been handled.</p>
<div class='pre p1 fill-light mt0'>isSignInPending(): <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean">Boolean</a></div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean">Boolean</a></code>:
<code>true</code>
if there is a pending sign in, otherwise
<code>false</code>
</section>
<section class='p2 mb2 clearfix bg-white minishadow'>
<div class='clearfix'>
<h3 class='fl m0' id='handlependingsignin'>
handlePendingSignIn
</h3>
</div>
<p>Try to process any pending sign in request by returning a <code>Promise</code> that resolves
to the user data object if the sign in succeeds.</p>
<div class='pre p1 fill-light mt0'>handlePendingSignIn(nameLookupURL: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>): <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>nameLookupURL</span> <code class='quiet'>(<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>
= <code>'https://core.blockstack.org/v1/names/'</code>)</code>
the endpoint against which to verify public
keys match claimed username
</div>
</div>
</div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code>:
that resolves to the user data object if successful and rejects
if handling the sign in request fails or there was no pending sign in request.
</section>
<section class='p2 mb2 clearfix bg-white minishadow'>
<div class='clearfix'>
<h3 class='fl m0' id='loaduserdata'>
loadUserData
</h3>
</div>
<p>Retrieves the user data object. The user's profile is stored in the key <code>profile</code>.</p>
<div class='pre p1 fill-light mt0'>loadUserData(): <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a></div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a></code>:
User data object.
</section>
<section class='p2 mb2 clearfix bg-white minishadow'>
<div class='clearfix'>
<h3 class='fl m0' id='isusersignedin'>
isUserSignedIn
</h3>
</div>
<p>Check if a user is currently signed in.</p>
<div class='pre p1 fill-light mt0'>isUserSignedIn(): <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean">Boolean</a></div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean">Boolean</a></code>:
<code>true</code>
if the user is signed in,
<code>false</code>
if not.
</section>
<section class='p2 mb2 clearfix bg-white minishadow'>
<div class='clearfix'>
<h3 class='fl m0' id='signuserout'>
signUserOut
</h3>
</div>
<p>Sign the user out and optionally redirect to given location.</p>
<div class='pre p1 fill-light mt0'>signUserOut(redirectURL: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>): void</div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>redirectURL</span> <code class='quiet'>(<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>
= <code>null</code>)</code>
Location to redirect user to after sign out.
</div>
</div>
</div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code>void</code>:
</section>
<section class='p2 mb2 clearfix bg-white minishadow'>
<div class='clearfix'>
<h3 class='fl m0' id='makeauthrequest'>
makeAuthRequest
</h3>
</div>
<p>Generates an authentication request that can be sent to the Blockstack
browser for the user to approve sign in.</p>
<div class='pre p1 fill-light mt0'>makeAuthRequest(transitPrivateKey: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>, redirectURI: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>, manifestURI: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>, scopes: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array">Array</a><<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>>, appDomain: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>, expiresAt: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">Number</a>): <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a></div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>transitPrivateKey</span> <code class='quiet'>(<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>
= <code>generateAndStoreTransitKey()</code>)</code>
hex encoded transit
private key
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>redirectURI</span> <code class='quiet'>(<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>
= <code>`${window.location.origin}/`</code>)</code>
location to redirect user to after sign in approval
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>manifestURI</span> <code class='quiet'>(<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>
= <code>`${window.location.origin}/manifest.json`</code>)</code>
location of this app's manifest file
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>scopes</span> <code class='quiet'>(<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array">Array</a><<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>>
= <code>DEFAULT_SCOPE</code>)</code>
the permissions this app is requesting
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>appDomain</span> <code class='quiet'>(<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>
= <code>window.location.origin</code>)</code>
the origin of this app
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>expiresAt</span> <code class='quiet'>(<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">Number</a>
= <code>nextHour().getTime()</code>)</code>
the time at which this request is no longer valid
</div>
</div>
</div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a></code>:
the authentication request
</section>
<section class='p2 mb2 clearfix bg-white minishadow'>
<div class='clearfix'>
<h3 class='fl m0' id='redirecttosigninwithauthrequest'>
redirectToSignInWithAuthRequest
</h3>
</div>
<p>Redirects the user to the Blockstack browser to approve the sign in request
given.</p>
<p>The user is redirected to the <code>blockstackIDHost</code> if the <code>blockstack:</code>
protocol handler is not detected. Please note that the protocol handler detection
does not work on all browsers.</p>
<div class='pre p1 fill-light mt0'>redirectToSignInWithAuthRequest(authRequest: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>, blockstackIDHost: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>): void</div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>authRequest</span> <code class='quiet'>(<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>
= <code>makeAuthRequest()</code>)</code>
the authentication request generated by
<code>makeAuthRequest</code>
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>blockstackIDHost</span> <code class='quiet'>(<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>
= <code>DEFAULT_BLOCKSTACK_HOST</code>)</code>
the URL to redirect the user to if the blockstack
protocol handler is not detected
</div>
</div>
</div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code>void</code>:
</section>
<section class='p2 mb2 clearfix bg-white minishadow'>
<div class='clearfix'>
<h3 class='fl m0' id='getauthresponsetoken'>
getAuthResponseToken
</h3>
</div>
<p>Retrieve the authentication token from the URL query</p>
<div class='pre p1 fill-light mt0'>getAuthResponseToken(): <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a></div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a></code>:
the authentication token if it exists otherwise
<code>null</code>
</section>
<div class='keyline-top-not py2'><section class='py2 clearfix'>
<h2 id='profiles' class='mt0'>
Profiles
</h2>
<p>Identity you own and control.</p>
<p><a href="https://github.com/blockstack/blockstack.js/blob/master/src/profiles/README.md">Read more about profiles</a></p>
</section>
</div>
<section class='p2 mb2 clearfix bg-white minishadow'>
<div class='clearfix'>
<h3 class='fl m0' id='extractprofile'>
extractProfile
</h3>
</div>
<p>Extracts a profile from an encoded token and optionally verifies it,
if <code>publicKeyOrAddress</code> is provided.</p>
<div class='pre p1 fill-light mt0'>extractProfile(token: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>, publicKeyOrAddress: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>): <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a></div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>token</span> <code class='quiet'>(<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>)</code>
the token to be extracted
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>publicKeyOrAddress</span> <code class='quiet'>(<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>
= <code>null</code>)</code>
the public key or address of the
keypair that is thought to have signed the token
</div>
</div>
</div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a></code>:
the profile extracted from the encoded token
<div class='py1 quiet mt1 prose-big'>Throws</div>
<ul>
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error">Error</a>: if the token isn't signed by the provided
<code>publicKeyOrAddress</code>
</li>
</ul>
</section>
<section class='p2 mb2 clearfix bg-white minishadow'>
<div class='clearfix'>
<h3 class='fl m0' id='wrapprofiletoken'>
wrapProfileToken
</h3>
</div>
<p>Wraps a token for a profile token file</p>
<div class='pre p1 fill-light mt0'>wrapProfileToken(token: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>): <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a></div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>token</span> <code class='quiet'>(<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>)</code>
the token to be wrapped
</div>
</div>
</div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a></code>:
including
<code>token</code>
and
<code>decodedToken</code>
</section>
<section class='p2 mb2 clearfix bg-white minishadow'>
<div class='clearfix'>
<h3 class='fl m0' id='signprofiletoken'>
signProfileToken
</h3>
</div>
<p>Signs a profile token</p>
<div class='pre p1 fill-light mt0'>signProfileToken(profile: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>, privateKey: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>, subject: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>, issuer: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>, signingAlgorithm: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>, issuedAt: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date">Date</a>, expiresAt: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date">Date</a>): <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a></div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>profile</span> <code class='quiet'>(<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>)</code>
the JSON of the profile to be signed
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>privateKey</span> <code class='quiet'>(<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>)</code>
the signing private key
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>subject</span> <code class='quiet'>(<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>
= <code>null</code>)</code>
the entity that the information is about
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>issuer</span> <code class='quiet'>(<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>
= <code>null</code>)</code>
the entity that is issuing the token
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>signingAlgorithm</span> <code class='quiet'>(<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>
= <code>'ES256K'</code>)</code>
the signing algorithm to use
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>issuedAt</span> <code class='quiet'>(<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date">Date</a>
= <code>new Date()</code>)</code>
the time of issuance of the token
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>expiresAt</span> <code class='quiet'>(<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date">Date</a>
= <code>nextYear()</code>)</code>
the time of expiration of the token
</div>
</div>
</div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a></code>:
the signed profile token
</section>
<section class='p2 mb2 clearfix bg-white minishadow'>
<div class='clearfix'>
<h3 class='fl m0' id='verifyprofiletoken'>
verifyProfileToken
</h3>
</div>
<p>Verifies a profile token</p>
<div class='pre p1 fill-light mt0'>verifyProfileToken(token: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>, publicKeyOrAddress: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>): <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a></div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>token</span> <code class='quiet'>(<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>)</code>
the token to be verified
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>publicKeyOrAddress</span> <code class='quiet'>(<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>)</code>
the public key or address of the
keypair that is thought to have signed the token
</div>
</div>
</div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a></code>:
the verified, decoded profile token
<div class='py1 quiet mt1 prose-big'>Throws</div>
<ul>
<li><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error">Error</a>: throws an error if token verification fails
</li>
</ul>
</section>
<section class='p2 mb2 clearfix bg-white minishadow'>
<div class='clearfix'>
<h3 class='fl m0' id='validateproofs'>
validateProofs
</h3>
</div>
<p>Validates the social proofs in a user's profile. Currently supports validation of
Facebook, Twitter, GitHub, Instagram, LinkedIn and HackerNews accounts.</p>
<div class='pre p1 fill-light mt0'>validateProofs(profile: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>, ownerAddress: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>, name: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>): <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>profile</span> <code class='quiet'>(<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>)</code>
The JSON of the profile to be validated
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>ownerAddress</span> <code class='quiet'>(<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>)</code>
The owner bitcoin address to be validated
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>name</span> <code class='quiet'>(<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>
= <code>null</code>)</code>
The Blockstack name to be validated
</div>
</div>
</div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code>:
that resolves to an array of validated proof objects
</section>
<section class='p2 mb2 clearfix bg-white minishadow'>
<div class='clearfix'>
<h3 class='fl m0' id='lookupprofile'>
lookupProfile
</h3>
</div>
<p>Look up a user profile by blockstack ID</p>
<div class='pre p1 fill-light mt0'>lookupProfile(username: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>, zoneFileLookupURL: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>): <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>username</span> <code class='quiet'>(<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>)</code>
The Blockstack ID of the profile to look up
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>zoneFileLookupURL</span> <code class='quiet'>(<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>
= <code>http://localhost:6270/v1/names/</code>)</code>
The URL
to use for zonefile lookup
</div>
</div>
</div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code>:
that resolves to a profile object
</section>
<div class='keyline-top-not py2'><section class='py2 clearfix'>
<h2 id='storage' class='mt0'>
Storage
</h2>
<p>Store your app's data without servers in storage your user controls.</p>
<p><em>Note: Blockstack Gaia Storage APIs and on-disk format will change in
upcoming pre-releases breaking backward compatibility. File encryption is currently
opt-in on a file by file basis.</em></p>
<p><em>Certain storage features such as and collections are not implemented in the current
version. These features will be rolled out in future updates.</em></p>
<p><a href="https://github.com/blockstack/blockstack.js/blob/master/src/storage/README.md">Read more about storage</a></p>
</section>
</div>
<section class='p2 mb2 clearfix bg-white minishadow'>
<div class='clearfix'>
<h3 class='fl m0' id='getfile'>
getFile
</h3>
</div>
<p>Retrieves the specified file from the app's data store.</p>
<div class='pre p1 fill-light mt0'>getFile(path: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>, options: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>): <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>path</span> <code class='quiet'>(<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>)</code>
the path to the file to read
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>options</span> <code class='quiet'>(<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>
= <code>null</code>)</code>
options object
</div>
<table class='mt1 mb2 fixed-table h5 col-12'>
<colgroup>
<col width='30%' />
<col width='70%' />
</colgroup>
<thead>
<tr class='bold fill-light'>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tbody class='mt1'>
<tr>
<td class='break-word'><span class='code bold'>options.decrypt</span> <code class='quiet'><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean">Boolean</a></code>
(default <code>false</code>)
</td>
<td class='break-word'><span>try to decrypt the data with the app private key
</span></td>
</tr>
<tr>
<td class='break-word'><span class='code bold'>options.username</span> <code class='quiet'><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a></code>
</td>
<td class='break-word'><span>the Blockstack ID to lookup for multi-player storage
</span></td>
</tr>
<tr>
<td class='break-word'><span class='code bold'>options.app</span> <code class='quiet'><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a></code>
</td>
<td class='break-word'><span>the app to lookup for multi-player storage -
defaults to current origin
</span></td>
</tr>
<tr>
<td class='break-word'><span class='code bold'>options.zoneFileLookupURL</span> <code class='quiet'><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a></code>
(default <code>http://localhost:6270/v1/names/</code>)
</td>
<td class='break-word'><span>the Blockstack
core endpoint URL to use for zonefile lookup
</span></td>
</tr>
</tbody>
</table>
</div>
</div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code>:
that resolves to the raw data in the file
or rejects with an error
</section>
<section class='p2 mb2 clearfix bg-white minishadow'>
<div class='clearfix'>
<h3 class='fl m0' id='putfile'>
putFile
</h3>
</div>
<p>Stores the data provided in the app's data store to to the file specified.</p>
<div class='pre p1 fill-light mt0'>putFile(path: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>, content: (<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a> | <a href="https://nodejs.org/api/buffer.html">Buffer</a>), options: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>): <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>path</span> <code class='quiet'>(<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>)</code>
the path to store the data in
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>content</span> <code class='quiet'>((<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a> | <a href="https://nodejs.org/api/buffer.html">Buffer</a>))</code>
the data to store in the file
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>options</span> <code class='quiet'>(<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a>
= <code>null</code>)</code>
options object
</div>
<table class='mt1 mb2 fixed-table h5 col-12'>
<colgroup>
<col width='30%' />
<col width='70%' />
</colgroup>
<thead>
<tr class='bold fill-light'>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tbody class='mt1'>
<tr>
<td class='break-word'><span class='code bold'>options.encrypt</span> <code class='quiet'><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean">Boolean</a></code>
(default <code>false</code>)
</td>
<td class='break-word'><span>encrypt the data with the app private key
</span></td>
</tr>
</tbody>
</table>
</div>
</div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code>:
that resolves if the operation succeed and rejects
if it failed
</section>
<section class='p2 mb2 clearfix bg-white minishadow'>
<div class='clearfix'>
<h3 class='fl m0' id='getappbucketurl'>
getAppBucketUrl
</h3>
</div>
<p>Get the app storage bucket URL</p>
<div class='pre p1 fill-light mt0'>getAppBucketUrl(gaiaHubUrl: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>, appPrivateKey: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>): <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>gaiaHubUrl</span> <code class='quiet'>(<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>)</code>
the gaia hub URL
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>appPrivateKey</span> <code class='quiet'>(<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>)</code>
the app private key used to generate the app address
</div>
</div>
</div>
<div class='py1 quiet mt1 prose-big'>Returns</div>
<code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code>:
That resolves to the URL of the app index file
or rejects if it fails
</section>
<section class='p2 mb2 clearfix bg-white minishadow'>
<div class='clearfix'>
<h3 class='fl m0' id='getuserappfileurl'>
getUserAppFileUrl
</h3>
</div>
<p>Fetch the public read URL of a user file for the specified app.</p>
<div class='pre p1 fill-light mt0'>getUserAppFileUrl(path: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>, username: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>, appOrigin: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>, zoneFileLookupURL: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>): <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></div>
<div class='py1 quiet mt1 prose-big'>Parameters</div>
<div class='prose'>
<div class='space-bottom0'>
<div>
<span class='code bold'>path</span> <code class='quiet'>(<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>)</code>
the path to the file to read
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>username</span> <code class='quiet'>(<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>)</code>
The Blockstack ID of the user to look up
</div>
</div>
<div class='space-bottom0'>
<div>
<span class='code bold'>appOrigin</span> <code class='quiet'>(<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a>)