SMART Health Card Decoder Library

A library to decode & verify encoded SMART Health Cards into a patient's FHIR data.

Expected usage is to have an application scan a SMART Health Card QR-code with a QR-scanner. The QR code is decoded into an shc string. This shc string is then passed to the verify() function along with a directory (a list of application permitted issuers/keys).
The shc string will then be decoded into an immunization 'card' with the signature being verified using the supplied directory:

// Basic usage

import {verify, Directory} from 'smart-health-card-decoder'

const resultFromQrScanner = 'shc:/56762909524 ... ';  // truncated

const vciDirectory = await Directory.create('vci'); // download daily VCI directory snapshot by default.

const result = await verify(resultFromQrScanner, vciDirectory);

if (result.verified === false) {
    const failureReason = result.reason;  // 'failed-validation' | 'bad-signature' | 'expired' | 'revoked'
    const failureErrors = result.data.errors;
    // handle errors
}

// success, do something with fhir data
const fhirBundle = result.data.fhirBundle;

The result.data object, returned above, is a Context object. See Context object for all the available data contained in this object.

See Directory for more information on the Directory class used above.

See VCI Directory for more information about the VCI Directory.

Install via GitHub

npm install github:smart-on-fhir/smart-health-card-decoder

// import the package
import {verify} from 'smart-health-card-decoder'

Browser

The library build script generates a bundled script for browser use.
Update the babel.config.json file to modify desired browser support.

<script src="\umd\smart-health-card-decoder.umd.js"></script>

<script>

    var smart = window['smart-health-card-decoder'];

    var directory = await smart.Directory.create(["https://spec.smarthealth.cards/examples/issuer"]);

    // Decode & Verify the QR-data
    var result = await smart.verify(qrUrl, directory);

    if (result.verified === false) {
        const failureReason = result.reason;  // 'failed-validation' | 'bad-signature' | 'expired' | 'revoked'
        const failureErrors = result.data.errors;
        // handle errors
    }

    // success, do something with fhir data
    const fhirBundle = result.data.fhirBundle;


</script>

Build from source

Alternatively, the package can be built from source following these steps.

1. Clone the source:

   git clone https://github.com/smart-on-fhir/smart-health-card-decoder.git
   cd smart-health-card-decoder

2. Build the package (install will trigger the build script through the prepare script):

   npm install

3. Optionally, run the tests:

   npm test

Examples

Using verify() with a constructed directory

import {verify} from 'smart-health-card-decoder'

// supply a directory of issuer-keysets to verify against
// an issuer may possess several keys in .keys[]
const myDirectory = {
    directory: "https://spec.smarthealth.cards/examples",
    time: "2022-02-28T22:38:31Z",
    issuerInfo: [
        {
            issuer: {
                iss: 'https://spec.smarthealth.cards/examples/issuer',
                name: 'smarthealth.cards'
            },
            keys: [
                {
                    kty: "EC",
                    kid: "3Kfdg-XwP-7gXyywtUfUADwBumDOPKMQx-iELL11W9s",
                    use: "sig",
                    alg: "ES256",
                    crv: "P-256",
                    x: "11XvRWy1I2S0EyJlyf_bWfw_TQ5CJJNLw78bHXNxcgw",
                    y: "eZXwxvO1hvCY0KucrPfKo7yAyMT6Ajc3N7OkAB6VYy8"
                }
            ]
        }
    ]
};

const encodedShc = 'shc:/56762909524 ... ';

const directory = await smart.Directory.create(myDirectory);

const result = await verify(encodedShc, directory);

if (result.verified === false) {
    const failureReason = result.reason;  // 'failed-validation' | 'bad-signature' | 'expired' | 'revoked'
    const failureErrors = result.data.errors;
    // handle errors
}

// success, do something with fhir data
const fhirBundle = result.data.fhirBundle;

Low Level API

See Low Level API for a list of more granular functions.