blockstack

0.10.2
Need help reading this?

Authentication

Single sign on and authentication without third parties or remote servers.

Read more about authentication

redirectToSignIn

Generates an authentication request and redirects the user to the Blockstack browser to approve the sign in request.

Please note that this requires that the web browser properly handles the blockstack: URL protocol handler.

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 generateAndStoreAppKey, makeAuthRequest, and redirectToSignInWithAuthRequest to build your own sign in process.

redirectToSignIn(redirectURI: String, manifestURI: String, scopes: Array): void
Parameters
redirectURI (String = `${window.location.origin}/`) The location to which the identity provider will redirect the user after the user approves sign in.
manifestURI (String = `${window.location.origin}/manifest.json`) Location of the manifest file.
scopes (Array = DEFAULT_SCOPE) Defaults to requesting write access to this app's data store. An array of strings indicating which permissions this app is requesting.
Returns
void:

isSignInPending

Check if there is a authentication request that hasn't been handled.

isSignInPending(): Boolean
Returns
Boolean: true if there is a pending sign in, otherwise false

handlePendingSignIn

Try to process any pending sign in request by returning a Promise that resolves to the user data object if the sign in succeeds.

handlePendingSignIn(nameLookupURL: String): Promise
Parameters
nameLookupURL (String = 'https://core.blockstack.org/v1/names/') the endpoint against which to verify public keys match claimed username
Returns
Promise: 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.

loadUserData

Retrieves the user data object. The user's profile is stored in the key profile.

loadUserData(): Object
Returns
Object: User data object.

isUserSignedIn

Check if a user is currently signed in.

isUserSignedIn(): Boolean
Returns
Boolean: true if the user is signed in, false if not.

signUserOut

Sign the user out and optionally redirect to given location.

signUserOut(redirectURL: String): void
Parameters
redirectURL (String = null) Location to redirect user to after sign out.
Returns
void:

makeAuthRequest

Generates an authentication request that can be sent to the Blockstack browser for the user to approve sign in.

makeAuthRequest(transitPrivateKey: String, redirectURI: String, manifestURI: String, scopes: Array<String>, appDomain: String, expiresAt: Number): String
Parameters
transitPrivateKey (String = generateAndStoreAppKey()) hex encoded app private key
redirectURI (String = `${window.location.origin}/`) location to redirect user to after sign in approval
manifestURI (String = `${window.location.origin}/manifest.json`) location of this app's manifest file
scopes (Array<String> = DEFAULT_SCOPE) the permissions this app is requesting
appDomain (String = window.location.origin) the origin of this app
expiresAt (Number = nextHour().getTime()) the time at which this request is no longer valid
Returns
String: the authentication request

redirectToSignInWithAuthRequest

Redirects the user to the Blockstack browser to approve the sign in request given.

The user is redirected to the blockstackIDHost if the blockstack: protocol handler is not detected. Please note that the protocol handler detection does not work on all browsers.

redirectToSignInWithAuthRequest(authRequest: String, blockstackIDHost: String): void
Parameters
authRequest (String = makeAuthRequest()) the authentication request generated by makeAuthRequest
blockstackIDHost (String = DEFAULT_BLOCKSTACK_HOST) the URL to redirect the user to if the blockstack protocol handler is not detected
Returns
void:

getAuthResponseToken

Retrieve the authentication token from the URL query

getAuthResponseToken(): String
Returns
String: the authentication token if it exists otherwise null

Profiles

Identity you own and control.

Read more about profiles

extractProfile

Extracts a profile from an encoded token and optionally verifies it, if publicKeyOrAddress is provided.

extractProfile(token: String, publicKeyOrAddress: String): Object
Parameters
token (String) the token to be extracted
publicKeyOrAddress (String = null) the public key or address of the keypair that is thought to have signed the token
Returns
Object: the profile extracted from the encoded token
Throws
  • Error: if the token isn't signed by the provided publicKeyOrAddress

wrapProfileToken

Wraps a token for a profile token file

wrapProfileToken(token: String): Object
Parameters
token (String) the token to be wrapped
Returns
Object: including token and decodedToken

signProfileToken

Signs a profile token

signProfileToken(profile: Object, privateKey: String, subject: Object, issuer: Object, signingAlgorithm: String, issuedAt: Date, expiresAt: Date): Object
Parameters
profile (Object) the JSON of the profile to be signed
privateKey (String) the signing private key
subject (Object = null) the entity that the information is about
issuer (Object = null) the entity that is issuing the token
signingAlgorithm (String = 'ES256K') the signing algorithm to use
issuedAt (Date = new Date()) the time of issuance of the token
expiresAt (Date = nextYear()) the time of expiration of the token
Returns
Object: the signed profile token

verifyProfileToken

Verifies a profile token

verifyProfileToken(token: String, publicKeyOrAddress: String): Object
Parameters
token (String) the token to be verified
publicKeyOrAddress (String) the public key or address of the keypair that is thought to have signed the token
Returns
Object: the verified, decoded profile token
Throws
  • Error: throws an error if token verification fails

validateProofs

Validates the social proofs in a user's profile. Currently supports validation of Facebook, Twitter, GitHub, Instagram, LinkedIn and HackerNews accounts.

validateProofs(profile: Object, ownerAddress: string, name: string): Promise
Parameters
profile (Object) The JSON of the profile to be validated
ownerAddress (string) The owner bitcoin address to be validated
name (string = null) The Blockstack name to be validated
Returns
Promise: that resolves to an array of validated proof objects

Storage

Store your app's data without servers in storage your user controls.

Note: Blockstack Gaia Storage APIs and on-disk format will change in upcoming pre-releases breaking backward compatibility. Certain storage features such as file encryption and collections are not implemented in the current version. These features will be rolled out in future updates.

Read more about storage

getFile

Retrieves the specified file from the app's data store.

getFile(path: String): Promise
Parameters
path (String) the path to the file to read
Returns
Promise: that resolves to the raw data in the file or rejects with an error

putFile

Stores the data provided in the app's data store to to the file specified.

putFile(path: String, content: (String | Buffer)): Promise
Parameters
path (String) the path to store the data in
content ((String | Buffer)) the data to store in the file
Returns
Promise: that resolves if the operation succeed and rejects if it failed