New HAT PDA onboarding and account management

DEX acts as the trust anchor on the HATDeX Platform, and in addition to verifying Data Plugs and Offers, it also verifies that only certified HAT PDAs participate in the exchange. What this means is that even though the core HAT is open-source and anyone could run their own copy, such HAT PDAs may not comply with the security requirements or the governance rules of the platform e.g. if they modify data exchange mechanisms, produce fraudulent data etc. It is therefore the responsibility of HAT Platform Providers who provision HAT PDAs as well as the HAT Community Foundation to certify the HAT PDAs that are can participate on the platform.

DEX recognises HAT clusters by the domain they are addressed under (e.g. hubat.net for the testing HAT PDAs) and assumes that once the domain manager has been certified, ensuring that individual HAT PDAs are compliant to platform rules is the responsibility of the HAT Platform Provider managing the domain.

Registering individual HAT PDAs

Individual HAT PDAs still need to be registered with DEX before they can connect Data Plugs, claim Offers or report any statistics. Registering a HAT PDA is done via an unauthenticated call:

{
  "request": {
    "method": "POST",
    "header": [
        {
            "key": "Content-Type",
            "value": "application/json",
            "description": ""
        }
    ],
    "body": {
        "mode": "raw",
        "raw": {
          "hatAddress": "postman.hubat.net"
        }
    },
    "url": "https://dex.hubofallthings.com/api/users/registerHat",
    "description": ""
  }
}

At this point, DEX verifies that the HAT PDA is up and running, retrieves its Public Key and stores it. The Public Key is used to verify validity of requests coming in from the HAT PDA by checking if the attached Access Token matches the stored public key.

Result of this security model with DEX is that HAT PDA addresses cannot easily be reused: if an address gets reused, the Private/Public key must be regenerated by a certified provisioning system, and requests from such HAT PDAs will no longer be authorized. The decision to restrict HAT PDA Address reuse has been made due to the fact that the address identifies the individual when logging in to other services, retrieving and exchanging data, etc. and the inherent risks do not justify the potential convenience gains.

Updating certified apps on a HAT PDA

Similarly to Data Plugs, new certified applications may be registered within the ecosystem after a HAT PDA gets created, resulting in the HAT PDA not recognising the app. Certain information, including access details may also need to change throughout the lifetime of the app. Therefore, DEX has the ability to update the details on selected HATs.

Properties of an app are:

Parameter Description
title Title (Name) of the app used for logging in
namespace Namespace where the app can write its data
description Textual description of the app
logoUrl URL of the logo for the app
url URL of the application to send the user to
authUrl Relative path within the URL for authentication, empty string if the main URL used
browser Boolean flag of whether or not the app is a full browser, i.e. allows user to manage their HAT fully
category Category of the app, e.g. "app" or "dataPlug"

Registering of an application (or updating them) is currently only available for the administrative accounts, however is done via a single call:

{
  "request": {
    "method": "POST",
    "header": [
      {
        "key": "X-Auth-Token",
        "value": "ACCESS_TOKEN",
        "description": ""
      },
      {
        "key": "Content-Type",
        "value": "application/json",
        "description": ""
      }
    ],
    "body": {
      "mode": "raw",
      "raw": {
        "title": "TestApp",
        "namespace": "testing",
        "description": "Test Application",
        "logoUrl": "/assets/images/testapp.png",
        "url": "https://example.com",
        "authUrl": "/signin/hat",
        "browser": true,
        "category": "app",
        "setup": true,
        "loginAvailable": true
      }
    },
    "url": "https://dex.hubofallthings.com/api/users/update-application?cluster=hubat.net&hatFilter=postman.hubat.net",
    "description": ""
  }
}