### blockstack

`0.13.1`
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 `generateAndStoreTransitKey`, `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 = `generateAndStoreTransitKey()`)` hex encoded transit 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. File encryption is currently opt-in on a file by file basis.

Certain storage features such as 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, decrypt: Boolean): Promise
Parameters
path `(String)` the path to the file to read
decrypt `(Boolean = `false`)` try to decrypt the data with the app private key
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), encrypt: Boolean): Promise
Parameters
path `(String)` the path to store the data in
content `((String | Buffer))` the data to store in the file
encrypt `(Boolean = `false`)` encrypt the data with the app private key
Returns
`Promise`: that resolves if the operation succeed and rejects if it failed

### encryptECIES

Encrypt content to elliptic curve publicKey using ECIES

encryptECIES(publicKey: String, content: (String | Buffer)): Object
Parameters
publicKey `(String)` secp256k1 public key hex string
content `((String | Buffer))` content to encrypt
Returns
`Object`: Object containing (hex encoded): iv (initialization vector), cipherText (cipher text), mac (message authentication code), ephemeral public key wasString (boolean indicating with or not to return a buffer or string on decrypt)

### decryptECIES

Decrypt content encrypted using ECIES

decryptECIES(privateKey: String, cipherObject: Object): Buffer
Parameters
privateKey `(String)` secp256k1 private key hex string
cipherObject `(Object)` object to decrypt, should contain: iv (initialization vector), cipherText (cipher text), mac (message authentication code), ephemeralPublicKey wasString (boolean indicating with or not to return a buffer or string on decrypt)
Returns
`Buffer`: plaintext, or false if error