Trustee Community

Check out the wiki for sequence diagram and more https://github.com/HIEofOne/Trustee-Community/wiki

Trustee Community is the code repository a community manager can fork to create a new patient community.

To create a new patient community, a manger will need these four things:

• An account at DigtialOcean to pay for hosting the community members Trustees (patient-controlled health records),
• An account at Stripe to collect credit card payments for Trustee subscriptions hosted by the community,
• A domain name for the community,
• A privacy policy describing the initial configuration of Trustee access policies and how subscribers can change the policies if they choose.

Installation

1. Gather all API keys for Magic, USPSTF, UMLS, DigitalOcean, and SendGrid

• have these ready for the installer in step 4
• details on getting API keys are in the section More on Additional API Services
• assume you have a domain name (mydomain.xyz) and email address needed for LetsEncrypt SSL (my@email.xyz)

2. Create a DigitalOcean Droplet with the minimum parameters:

• size: 's-1vcpu-1gb',
• image: 'ubuntu-22-10-x64'

3. Login to the console (should be root user) and enter this command:

git clone -b deploy --single-branch https://github.com/HIEofOne/Trustee-Community.git
cd Trustee-Community
./do-install.sh

4. The first pass will install all dependencies. Logout and login to the droplet.

exit
cd Trustee-Community
./do-install.sh

5. Open your browser to https://mydomain.xyz

• Other notable endpoints with your Trustee include:
• https://db.mydomain.xyz which points to the CouchDB database used to store user account information (just email) and droplet info.
• https://router.mydomain.xyz which points to the Traefik reverse proxy router

More on Additional API Services

Magic instructions:

1. Set up an account for free by visiting Magic. Click on Start now.

2. Once you are in the dashboard, go to Magic Auth and click on New App. Enter the App Name (My App Powered by Trustee) and hit Create App.

3. Once you are in the home page for the app, scroll down to API Keys and copy the PUBISHABLE API KEY value. This API Key will be usee to interact with Magic's APIs

National Library of Medicine UMLS Terminology Services - this is to allow search queries for SNOMED CT LOINC, and RXNorm definitions.

1. Set up an account here

2. Edit your profile and click on Generate new API Key. Copy this API key.

US Preventive Services Task Force - this provides Care Opportunties guidance based on USPSTF guidelines

1. Visit this site for instructions

Architecture

Trustee is based around Docker containers. This repository source code is for the Trustee core which is Next.JS based application and served by Node.JS. Deployment of individual Docker containers which includes the patient health record powered by NOSH specific to only one patient/user is demonstrated by this project.

The docker-compose.yml (template found in docker-compose.tmp under the docker directory) defines the specific containers that when working together, allow Trustee to be able to fully featured (e.g. a bundle). Below are the different containers and what they do:

1. Traefik - this is the router, specifying the ports and routing to the containers in the bundle

2. CouchDB - this is the NoSQL database that stores all documents

3. NOSH - this is the Node.js based server application

4. Watchtower - this service pulls and applies updates to all Docker Images in the bundle automatically without manager intervention

Developer API

Get all patients

GET /api/couchdb/patients/all

Grant Negotiation and Authorization Protocol (GNAP)

Trustee also functions as an Authorization Server as specified by the Grant Negotiation and Authorization Protocol.

1. Requesting Access

Client sends HTTP POST to the grant endpoint of Trustee with the following headers and body. The Content-Digest, Signature, and Signature-Input fields and how they are constructed are described here. It is imperative that the processes outlined in the aformentioned link are followed explicitly as Trustee verifies these header fields with the public key presented in the request body (client.key field) NOTE: Trustee currently only accepts JSON Web Keys for the public key presentation at this time (in the client.key field)

POST /api/as/tx
Content-Type: application/json
Signature-Input: sig1=...
Signature: sig1=:...
Content-Digest: sha-256=...
{
  "access_token": {
    "access": [
      {
        "type": "app",
        "actions": [
          "read",
          "write"
        ],
        "locations": [
          "https://nosh-app-mj3xd.ondigitalocean.app/app/chart/nosh_49798bcb-c617-4165-beb6-05442152c99a"
        ],
        "datatypes": [
          "application"
        ]
      },
      {
        "type": "conditions",
        "actions": [
          "read",
          "write"
        ],
        "locations": [
          "https://nosh-app-mj3xd.ondigitalocean.app/fhir/api/Condition"
        ],
        "datatypes": [
          "application/json"
        ]
      }
    ]
  },
  "client": {
    "display": {
      "name": "My Client Display Name",
      "uri": "https://client.example.net"
    },
    "key": {
      "proof": "httpsig",
      "jwk": {
        "kty": "RSA",
        "e": "AQAB",
        "kid": "xyz-1",
        "alg": "RS256",
        "n": "kOB5rR4Jv0GMeL...."
      }
    }
  },
  "interact": {
    "start": ["redirect"],
    "finish": {
      "method": "redirect",
      "uri": "https://client.example.net/return/123455",
      "nonce": "LKLTI25DK82FX4T4QFZC"
    }
  },
  "subject": {
    "sub_id_formats": ["iss_sub", "opaque"],
    "assertion_formats": ["id_token"]
  }
}

If verified successfuly, Trustee responds with:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store

{
    "interact": {
      "redirect":
        "https://server.example.com/api/as/interact/4CF492MLVMSW9MKM",
      "finish": "MBDOFXG4Y5CVJCX821LH"
    }
    "continue": {
      "access_token": {
        "value": "80UPRY5NM33OMUKMKSKU"
      },
      "uri": "https://server.example.com/api/as/continue"
    },
    "instance_id": "7C7C4AZ9KHRS6X63AJAO"
}