• Public
  • Public/Protected
  • All

Class UserSession

Represents an instance of a signed in user for a particular app.

A signed in user has access to two major pieces of information about the user, the user's private key for that app and the location of the user's gaia storage bucket for the app.

A user can be signed in either directly through the interactive sign in process or by directly providing the app private key.


  • UserSession






appConfig: AppConfig




  • decryptContent(content: string, options?: object): Promise<Buffer | string>
  • Decrypts data encrypted with encryptContent with the transit private key.


    • content: string

      encrypted content.

    • Optional options: object
      • Optional privateKey?: string

        The hex string of the ECDSA private key to use for decryption. If not provided, will use user's appPrivateKey.

    Returns Promise<Buffer | string>

    decrypted content.


  • deleteFile(path: string, options?: object): Promise<void>
  • Deletes the specified file from the app's data store.


    • path: string

      The path to the file to delete.

    • Optional options: object

      Optional options object.

      • Optional wasSigned?: boolean

        Set to true if the file was originally signed in order for the corresponding signature file to also be deleted.

    Returns Promise<void>

    Resolves when the file has been removed or rejects with an error.


  • Encrypts the data provided with the app public key.


    Returns Promise<string>

    Stringified ciphertext object


  • generateAndStoreTransitKey(): string
  • Generates a ECDSA keypair to use as the ephemeral app transit private key and store in the session.

    Returns string

    the hex encoded private key


  • getAuthResponseToken(): string
  • Retrieve the authentication token from the URL query.

    Returns string

    the authentication token if it exists otherwise null


  • getFile(path: string, options?: GetFileOptions): Promise<string | ArrayBuffer>
  • Retrieves the specified file from the app's data store.


    Returns Promise<string | ArrayBuffer>

    that resolves to the raw data in the file or rejects with an error


  • Get the URL for reading a file from an app's data store.


    Returns Promise<string>

    that resolves to the URL or rejects with an error



  • handlePendingSignIn(authResponseToken?: string): Promise<UserData>
  • Try to process any pending sign in request by returning a Promise that resolves to the user data object if the sign in succeeds.


    • Default value authResponseToken: string = this.getAuthResponseToken()

      the signed authentication response token

    Returns Promise<UserData>

    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.


  • isSignInPending(): boolean
  • Check if there is a authentication request that hasn't been handled.


    true if there is a pending sign in, otherwise false

    Returns boolean


  • isUserSignedIn(): boolean
  • Check if a user is currently signed in.

    Returns boolean

    true if the user is signed in, false if not.


  • listFiles(callback: function): Promise<number>
  • List the set of files in this application's Gaia storage bucket.


    • callback: function

      a callback to invoke on each named file that returns true to continue the listing operation or false to end it

        • (name: string): boolean
        • Parameters

          • name: string

          Returns boolean

    Returns Promise<number>

    that resolves to the number of files listed



  • makeAuthRequest(transitKey?: string, redirectURI?: string, manifestURI?: string, scopes?: Array<AuthScope | string>, appDomain?: string, expiresAt?: number, extraParams?: any): string
  • Generates an authentication request that can be sent to the Blockstack browser for the user to approve sign in. This authentication request can then be used for sign in by passing it to the redirectToSignInWithAuthRequest method.

    Note: This method should only be used if you want to use a customized authentication flow. Typically, you'd use redirectToSignIn which is the default sign in method.


    • Optional transitKey: string

      A HEX encoded transit private key.

    • Optional redirectURI: string

      Location to redirect the user to after sign in approval.

    • Optional manifestURI: string

      Location of this app's manifest file.

    • Optional scopes: Array<AuthScope | string>

      The permissions this app is requesting. The default is store_write.

    • Optional appDomain: string

      The origin of the app.

    • Default value expiresAt: number = nextHour().getTime()

      The time at which this request is no longer valid.

    • Default value extraParams: any = {}

      Any extra parameters to pass to the authenticator. Use this to pass options that aren't part of the Blockstack authentication specification, but might be supported by special authenticators.

    Returns string

    the authentication request


  • putFile(path: string, content: string | Buffer | ArrayBufferView | Blob, options?: PutFileOptions): Promise<string>
  • Stores the data provided in the app's data store to to the file specified.


    • path: string

      the path to store the data in

    • content: string | Buffer | ArrayBufferView | Blob

      the data to store in the file

    • Optional options: PutFileOptions

      a PutFileOptions object

    Returns Promise<string>

    that resolves if the operation succeed and rejects if it failed


  • redirectToSignIn(redirectURI?: string, manifestURI?: string, scopes?: Array<AuthScope | string>): void
  • 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.


    • Optional redirectURI: string

      Location of your application.

    • Optional manifestURI: string

      Location of the manifest.json file

    • Optional scopes: Array<AuthScope | string>

      Permissions requested by the application. Possible values are store_write (default) or publish_data.

    Returns void


  • redirectToSignInWithAuthRequest(authRequest?: string, blockstackIDHost?: string): void
  • Redirects the user to the Blockstack browser to approve the sign in request. To construct a request see the makeAuthRequest function.

    The user is redirected to the authenticator URL specified in the AppConfig if the blockstack: protocol handler is not detected. Please note that the protocol handler detection does not work on all browsers.


    • Optional authRequest: string

      A request string built by the makeAuthRequest function

    • Optional blockstackIDHost: string

      The ID of the Blockstack Browser application.

    Returns void

Private setLocalGaiaHubConnection

  • These two functions are app-specific connections to gaia hub, they read the user data object for information on setting up a hub connection, and store the hub config to localstorage

    Returns Promise<GaiaHubConfig>

    that resolves to the new gaia hub connection


  • signUserOut(redirectURL?: string): void
  • Sign the user out and optionally redirect to given location.


    • Optional redirectURL: string

      Location to redirect user to after sign out. Only used in environments with window available

    Returns void

Generated using TypeDoc