Hive Authentication Client (HAC)

Hive Authentication Client (HAC) is a password less users authentication, sign and broadcast transactions for the HIVE Blockchain through the Hive Authentication Services (HAS) or Hive Keychain Browser Extension (KBE).

Authentications and transactions are performed by the wallet supporting the HAS protocol or the Hive Keychain Browser Extension without communicating the private key, which thus remains secure. The results of each operation are sent by subscription (RxJS).

Hive Authentication Client (HAC) manages previous connections as well through encrypted data in the localStorage.

Hive Authentication Services (HAS)

Manage the WebSocket connection to the HAS and all communication with it. Support reconnection to another HAS WebSocket server in case of failure.

Hive Keychain Browser Extension (KBE)

Manage the communication with the Hive Keychain Browser Extension if present

Getting Started

Installation

Using npm:

$  npm install @mintrawa/hive-auth-client --save

Using browser:

<script type="module" src="./dist/hive-auth-client.min.js"></script>

From the source:

clone the repository

$  git clone https://github.com/Mintrawa/hive-auth-client.git

Build for NodeJS/Angular... in "./lib" directory

$  npm run build

Build for browser (minified) in "./dist" directory

$  npm run build-browser

Initialisation

Initialise the Hive Authentication Client with params

import { HiveAuthClient } from "@mintrawa/hive-auth-client"

/** Init the Hive Authentication Client */
HiveAuthClient(["HAS server"], { debug: true })

or without params just

import { HiveAuthClient } from "@mintrawa/hive-auth-client"

/** Init the Hive Authentication Client */
HiveAuthClient()

Params

• has (optional): array of HAS server (default: ["wss://hive-auth.arcange.eu"])
• options (optional):
  • debug (boolean): if true activate console.log (default: false)
  • delay (number): delay in ms before to check the avaibility of Hive Keychain (default: 200)

On Angular app a delay is needed before the avaibility of a browser extension

Hive Authentication Client Message subscription

All returns of information from HAC, HAS or KBE are managed by RxJS messages subscription.

hacMsg.subscribe()

Use of RxJS to send the result of user authentication and transaction signing and broadcasting.

Usage

import { hacMsg } from "@mintrawa/hive-auth-client"

/** Subscribe results */
hacMsg.subscribe({
  next: async message => {
    ...
  },
  error: error => {
    ...
  }
})

message

{
  "type": string
  "msg"?: {
    "result": {
      ...
    } 
  },
  "error"?: {
    "msg": string
  }
}

Functions

Main

hacGetConnectionStatus()

Retrieve the status of keychain and the connection status to the Hive Authentication Services (HAS)

Usage

import { hacGetConnectionStatus } from "@mintrawa/hive-auth-client"

/** [HAS] Get the status of the connection */
hacGetConnectionStatus()

Result

{
  "keychain": boolean
  "has": {
    "status": "connected"|"disconnected"
    "ping_rate": number
    "protocol": number
    "server": string
    "socketid": string
    "timeout": number
    "version": string
  }
}

hacGetAccounts()

Get the array of all account known for this browser or of one specific account if specified

Params

• account (optional): HIVE username to retrieve
• pwd (optional): password to decrypt the data if it's the first call

Usage

import { hacGetAccounts } from "@mintrawa/hive-auth-client"

/**
 * [HAC] Get all or one specific connection info
 * @param { string } [account] - Account to retrieve
 * @param { string } [pwd] - Password to use to decrypt localStorage
 * @returns HAC_PREVIOUS_CONNECTION[]
 */
hacGetAccounts()

Result

[{
  account: string
  has?: {
    auth_key:   string
    has_token:  string
    has_expire: number
    has_server: string
  },
  hkc: boolean,
  challenge: {
    value: string
    signature: string
  }
}]

hacRemoveAccount()

Remove an account from the storage

Params

• account: HIVE username to remove

Usage

import { hacRemoveAccount } from "@mintrawa/hive-auth-client"

/**
 * [HAC] Remove an account
 * @param { string } account 
 * @returns boolean
 */
hacRemoveAccount(mintrawa)

Return true or false

hacCheckPwd()

Check the validity of the string password used to encrypt the localStorage

Params

• pwd: string to encrypt the localStorage

Usage

import { hacCheckPwd } from "@mintrawa/hive-auth-client"

/**
 * [HAC] Check password
 * @param { string } pwd
 * @returns boolean
 */
hacCheckPwd(mintrawa)

Return true or false

hacUserAuth()

Authentication of the HIVE user through the HAS or KBE

Params

• account: HIVE username to connect
• app: HAS_APP* information
• pwd: string to encrypt the localStorage
• challenge: object with private key_type ("active"|"posting") to use and string to sign
• m (optional): module to use "has"|"keychain" (default: "has")

HAS_APP* need to be on the form of:

{
  "name": string = short name of the app (ex: "peakd")
  "description"?: string = description of the app (ex: "Peakd for Hive"),
  "icon"?: string = URL to retrieve the application icon (ex: "https://peakd.com/logo.png")
}

Usage

import { hacUserAuth } from "@mintrawa/hive-auth-client"

/**
 * HAC User Authentication
 * @param { string }     account - Hive username to connect
 * @param { HAS_APP }    app - App
 * @param { string }     pwd - Password to use to encrypt localStorage
 * @param { string }     challenge - String to sign with Hive User private key 
 * @param { HAC_MODULE } [m] - Module to use (has, keychain)
 * @returns void
 */
hacUserAuth("mintrawa", { name: 'HACtutorial' }, "MyPa$$w0rd", { key_type: 'active', value: "MyCha11en6e" })

Result through subscription (RxJS)

{
  type: "authentication"
  msg?: {
    status: "authentified"|"rejected"
    data?: {
      challenge:   string
      has_token?:  string
      has_expire?: number
      has_server?: string
    } 
  },
  error?: {
    msg: string
  }
}

Operations

hacManualTransaction()

Send a Manual Transaction

Params

• key_type: "owner"|"active"|"posting"|"memo"
• op: Operation recognize by the HIVE Blockchain, more info: Hive Developer Portal

Usage

import { hacManualTransaction } from "@mintrawa/hive-auth-client"

/**
 * HAC Send a Manual Transaction
 * @param { "owner"|"active"|"posting" } key_type 
 * @param { OPERATION } op 
 */
hacManualTransaction("active", [ "claim_account", { fee: "0.000 HIVE", creator: "mintrawa", extensions: [] } ])

Result through subscription (RxJS)

{
  type: "tx_result"
  msg?: {
    status:     "accepted"|"rejected"|"signature"|"error"
    uuid?:      string
    broadcast?: boolean
    data?:      unknown
  },
  error?: {
    msg: string
  }
}

Operations specifics

In order to save time on the learning curve of the HIVE blockchain, some operations exist in short version

• hacFollowing(following: string, follow: boolean)
• hacVote(author: string, permlink: string, weight: number)
• hacTransfer(to: string, amount: string, currency: "HIVE"|"HBD", memo: string)
• hacTransferToVesting(to: string, amount: string)
• hacWithdrawVesting(vesting_shares: string)
• hacDelegation(delegatee: string, vesting_shares: string)
• hacConvert(amount: string, currency: "HIVE"|"HBD")
• hacWitnessVote(witness: string, approve: boolean)
• hacWitnessProxy(proxy: string)

Examples

https://stackblitz.com/edit/angular-ivy-ew73hs

https://github.com/Mintrawa/hac-tutorial

Contributing

Pull requests for new features, bug fixes, and suggestions are welcome!

License

Copyright (C) 2021 @mintrawa (https://hive.blog/@mintrawa)

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.