Integrating HAS (Hive Authentication Services) on your website

The Hive Authentication Services provide a way for any applications, (either web, desktop or mobile) to easily authenticate users without asking them to provide any password or private key.
Source: https://docs.hiveauth.com/

In the following paragraphs I will be describing the process on how to integrate HAS on your website.
The first step is to install the required npm package by running

npm install hive-auth-wrapper --save

Then you may test out the HAS connection by importing the HAS object and checking the status

import HAS from 'hive-auth-wrapper'

const status = HAS.status()
console.log(status)

which should print something like

{host: 'wss://hive-auth.arcange.eu/', connected: false, timeout: 60000}

Next you need to define a metadata object for identifying your application upon an authentication requests:

  const APP_META = {
    name: "name of the app",
    description: "description of the app",
    icon: "url pointing to app logo",
  };

Create a login dialog with an input field for the username:

and after the click on login set it on an auth object

const auth = {
    username: username,
    token: undefined,
    expire: undefined,
    key: undefined,
};

and send the authentication request to HAS with an optional challenge_data object:

const challenge_data = {
  key_type: 'posting',
  challenge: JSON.stringify({
    login: auth.username,
    ts: Date.now(),
  })
}
HAS.authenticate(auth, APP_META, challenge_data, (evt) => {
      // process the auth_wait event
  }))
  .then(res => {
    // the authentication request was successful
  })
  .catch(err => {
    // the authentication request expired, was canceled or an error occurred
  });

In case the user is not authenticated yet an auth_wait event will occur, which needs to be handled by generating a HAS authentication request url. This is done by first creating an authentication payload object, encoding it in base64 and creating an url from that:

const authPayload = {
  account: username,
  uuid: evt.uuid,
  key: evt.key,
  host: status.host,
};
const encoded = btoa(JSON.stringify(authPayload));
const url = `has://auth_req/${encoded}`;

The url is then best shown to the user in form of a QR code:

Now the user needs to open e.g. Hive Keychain, scan the QR code and approve the request. After 60 seconds the request will expire and if the user cancels the request a auth_nack event will be fired.

In case the user successfully signs the request a auth_ack will occur, which means the user was successfully signed in and the token, expire and key will be updated in the auth object accordingly.
If we want to restore the session when the user next visits the site we need to store the auth object e.g. in local storage. We can restore the session by loading the auth object and simply checking:

if(auth?.token && auth?.expire > Date.now()) {
  // session is still valid and user can be signed in
} else {
  // session has expired and user needs to sign in again
}

If you want to broadcast a transaction for the logged in user you can use the auth object and an op array containing the actual operation

HAS.broadcast(auth, "posting", [op], (evt)=> {
    // process sign_wait message
}) )
.then(res => {
  // transaction approved and broadcasted
} )
.catch(err => {
  // transaction failed or rejected
} );

and handle the response in case of success or failure accordingly.

I am almost done with integrating HAS into my monitor site, but more on that once the process is completed.

Thanks @arcange et al. for this awesome new service and thank you for your great presentation(s) at HiveFest, which motivated me to integrate this into my site. Unfortunately I could only watch the live stream, but hopefully next year I will make it there in person :)

If you found this useful and need more details / help integrating this into your site please let me know or check out the official docs, which are also very useful https://docs.hiveauth.com.

Please consider voting me as HIVE witness, so I can build more awesome stuff.