HealthCards

This repository includes a Ruby gem for SMART Health Cards and a reference implementation for the SMART Health Cards: Vaccination & Testing Implementation Guide. Go to the Health Card Gem section to read about the Ruby library or go to the Reference Implementation section to try a ready-to-use rails application.

Reference Implementation

The reference implementation is a Ruby on Rails application with Issuer capabilities for creating SMART Health Cards and Verifier capabilities for confirming an individual's vaccination status or laboratory test results.

This Issuer supports the three defined methods of retrieving a SMART Health Card:

• via a *.smart-health-card file
• via a QR code
• via FHIR $health-card-issue operation

The Verifier supports scanning QR codes.

System Requirements

• Ruby 2.7 (prior versions may work but are not tested)
• Bundler
• Node.js
• Yarn

Quick Start

Clone and change directory into the repository:

git clone https://github.com/dvci/health_cards.git
cd health_cards

Local Development

Setup environment:

bin/setup

Run server:

bin/rails server

Then go to http://127.0.0.1:3000 to view the locally running application.

Docker:

Alternatively, you can create a Docker image and start it in a container:

docker build -t health_cards .
docker run -p 3000:3000 --env HOST=https://myserver.com health_cards

The HOST environment variable will be used as the iss value in the SMART Health Card JWS. By default this value is http://localhost:3000. The Docker container will be running at http://127.0.0.1:3000, unless mapped to a different port.

Docker Compose

Docker Compose can be used to deploy a production version of the application behind nginx and is especially useful for deploying behind an SSL terminating load balancer.

docker-compose up --build

There are two environment variables which can be configured:

• HEALTH_CARDS_HOST is used as the iss value in issued Health Cards and for identifying the SMART Endpoint locations
• HEALTH_CARDS_SECRET_KEY_BASE is used by rails as the input secret to the application's key generator, which in turn is used to create all MessageVerifiers/MessageEncryptors, including the ones that sign and encrypt cookies. See secret_key_base

When deploying a production instance it is important that a new secret base is generated and used. A new secret base can be generated with bin/rails secret.

When testing locally proxy_set_header X-Forwarded-Ssl on; should be commented out in nginx/nginx.conf.

Health Cards Gem

Health Cards is a Ruby gem that implements SMART Health Cards, a framework for sharing verifiable clinical data with HL7 FHIR and JSON Web Signatures (JWS) which may then be embedded into a QR code, exported to a *.smart-health-card file, or returned by a $health-card-issue FHIR operation.

This library also natively supports SMART Health Cards: Vaccination & Testing Implementation Guide specific cards.

Installation

Add this line to your application's Gemfile:

gem 'health_cards'

And then execute:

 $ bundle install

Or install it yourself as:

 $ gem install health_cards

Documentation

See usage examples in USAGE.md.

See full documentation in API.md.

Development

Fork or clone this repository, then run bin/setup or bundle install to install dependencies. Run tests with rake test. Access an interactive prompt for experimentation with bin/console.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/dvci/health_cards. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

Copyright 2021 The MITRE Corporation

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Code of Conduct

Everyone interacting in the HealthCards project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.