Hive Authentication Services - Integrating HAS into your applicatio...

alt

With the release of the official HAS Documentation, the integration of the Hive Authentication Services into applications is accelerating.

One of the particularities of the HAS protocol is that it does not rely on calls to an API but on the exchange of messages through a WebSocket connection.

The advantage is to have asynchronous and more efficient communication between the application and the HAS infrastructure. The counterpart is that applications may have to adapt their code and logic to set up event management.

Introducing the HAS Wrapper Library

To simplify the task of developers, I created a Javascript library that makes it easy to integrate HAS support into an application.

It relieves developers from managing a WebSocket connection and the events it generates. It allows you to use the functionality of the HAS infrastructure in the same way as you would with a traditional API.

Installation

To install the library, use the following command:

npm install hive-auth-wrapper

then simply import it into your code:

import HAS from 'hive-auth-wrapper'

That's it. As soon it is created, the wrapper object is ready to interact with the HAS infrastructure.

Configuration

The HAS wrapper should work with its default configuration. However, you can change it by calling setOptions(options). The options object has the following structure:

{
  host: string = undefined,
  auth_key_secret: string = undefined
}

host: (optional) HAS server to connect to (default to wss://hive-auth.arcange.eu)
auth_key_secret: (optional) the PKSA pre-shared encryption key to use to encrypt any auth_key passed with an auth_req payload.

NOTE: auth_key_secret should be defined only if you are running your own PKSA in service mode and the app sends the auth_key online with the auth_req payload!

Authentication

When the app performs its first authentication, it can use an auth object with an undefined token and expire properties. The auth.token and auth.expire will be updated if the authentication succeeds.

// Your application information
const APP_META = {
  name: "myapp", 
  description:" My HAS compatible application",
  icon: "https://my.appdomain.com/icon.png"
}

// Create an authentication object
const auth = {
  username: "username"  // (required)
  token: undefined
  expire: undefined
  key: undefined
}

If the app already owns an auth object with a token that has not expired, it can reuse it without calling authenticate() again.

if(auth.token && auth.expire > Date.now()) {
    // token exists and is still valid - no need to login again
    resolve(true)
} else {
    HAS.authenticate(auth, APP_META, (evt) => {
        console.log(evt)    // process auth_wait message
    }))
    .then(res => resolve(res))  // Authentication request approved
    .catch(err => reject(err))  // Authentication request rejected or error occured
}

Broadcasting transactions

The APP can request the PKSA to sign and/or broadcast a transaction.

const op = [ "vote", { voter:auth.username, author:author, permlink:permlink, weight:weight } ]
HAS.broadcast(auth, "posting", [op], (evt)=> {
    console.log(evt)    // process sign_wait message
}) )
.then(res => resolve(res) ) // transaction approved and successfully broadcasted
.catch(err => reject(err) ) // transaction rejected or failed

Signing a challenge

Apps may want to validate an account by asking it to sign a predefined text string (challenge) with one of its keys.

try {
    const challenge = JSON.stringify({login:auth.username,ts:Date.now()})
    const res = await HAS.challenge(auth, "posting",challenge)
    
    // Validate signature against account public key
    const sig = ecc.Signature.fromHex(resC.data.challenge)
    const buf = ecc.hash.sha256(challenge, null, 0)
    const verified = sig.verifyHash(buf, ecc.PublicKey.fromString(resC.data.pubkey));
    
    if(verified) {
        console.log("challenge succeeded")
    } else {
        console.error("challenge failed")
    }
} catch(e) {
    console.error("challenge failed")
}

Conclusion

As you can see, using the library greatly simplifies the code to write to implement support of the Hive Authentication Services into your applications.

Another advantage of using this library is that you don't have to adapt your own code if the HAS protocol is updated. Just update the library and you're done.

I have been using this library for more months when integrating HAS into Engage, my Communication Management application. This has made the code battle-tested and you can play with the HAS compatible version of Engage available here.

The hive-auth-wrapper library is open-source

As promised in the HAS proposal, the code of the library is open-source on GitHub.
This will allow developers who would like to integrate native WebSocket support for the HAS protocol in their application to draw inspiration from it.

And of course, the HiveAuth documentation has been updated accordingly.

Thanks for reading.