health_cards 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f299c1c4dec501f53d77e64007a9805316974ea5e649b1918f413e52ffc0dbf4
+  data.tar.gz: 118a46c61178a67461d0ee3fbeedab15ea4b0f93433ece7add27aceb1f398e0c
+SHA512:
+  metadata.gz: d9765d939d22cd01ff11b5c20a29d413af83124970ecb06cf89abc0b7cff393080ae12a908e22de411b991aa05ecaaddeb2023a9192aaab741379ecffd9a5c4a
+  data.tar.gz: 1102f68ec1d832766ecd37c15fd790ff3ab0e7d8505468dcf210d3b97d516900d5876a2aa7e5de963bad9667b4c48d654b5fcec733f3b3a141dd4f84b9d19097

data/LICENSE.txt

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   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.

data/lib/health_cards.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'health_cards/version'
+require 'health_cards/encoding'
+require 'health_cards/issuer'
+require 'health_cards/key'
+require 'health_cards/jws'
+require 'health_cards/key_set'
+require 'health_cards/private_key'
+require 'health_cards/public_key'
+require 'health_cards/health_card'
+require 'health_cards/chunking'
+require 'health_cards/exceptions'
+require 'health_cards/verifier'
+require 'health_cards/importer'
+require 'health_cards/covid_health_card'
+require 'health_cards/exporter'
+
+require 'base64'
+require 'fhir_models'
+
+module HealthCards
+  class Error < StandardError; end
+  # Your code goes here...
+end

data/lib/health_cards/chunking.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module HealthCards
+  # Split up a JWS into chunks if encoded size is above QR Code Size constraint
+  module Chunking
+    extend self
+    MAX_SINGLE_JWS_SIZE = 1195
+    MAX_CHUNK_SIZE = 1191
+
+    def split_bundle(jws)
+      if jws.length <= MAX_SINGLE_JWS_SIZE
+        [jws]
+      else
+        chunk_count = (jws.length / MAX_CHUNK_SIZE.to_f).ceil
+        chunk_size  = (jws.length / chunk_count.to_f).ceil
+        jws.scan(/.{1,#{chunk_size}}/)
+      end
+    end
+
+    # Splits jws into chunks and converts each string into numeric
+    def generate_qr_chunks(jws)
+      jws_chunks = split_bundle jws.to_s
+      jws_chunks.map { |c| convert_jws_to_numeric(c) }
+    end
+
+    # Assemble jws from qr code chunks
+    def assemble_jws(qr_chunks)
+      if qr_chunks.length == 1
+        # Strip off shc:/ and convert numeric jws
+        numeric_jws = qr_chunks[0].delete_prefix('shc:/')
+        convert_numeric_jws numeric_jws
+      else
+        ordered_qr_chunks = strip_prefix_and_sort qr_chunks
+        ordered_qr_chunks.map { |c| convert_numeric_jws(c) }.join
+      end
+    end
+
+    def get_payload_from_qr(qr_chunks)
+      jws = assemble_jws qr_chunks
+
+      # Get JWS payload, then decode and inflate
+      message = Base64.urlsafe_decode64 jws.split('.')[1]
+      JSON.parse(Zlib::Inflate.new(-Zlib::MAX_WBITS).inflate(message))
+    end
+
+    private
+
+    # Each character "c" of the jws is converted into a sequence of two digits by taking c.ord - 45
+    def convert_jws_to_numeric(jws)
+      jws.chars.map { |c| format('%02d', c.ord - 45) }.join
+    end
+
+    def convert_numeric_jws(numeric_jws)
+      result_jws = ''.dup
+      numeric_jws.chars.each_slice(2) do |a, b|
+        result_jws << ((a + b).to_i + 45).chr
+      end
+      result_jws
+    end
+
+    def strip_prefix_and_sort(qr_chunks)
+      # Multiple QR codes are prefixed with 'shc:/C/N' where C is the index and N is the total number of chunks
+      # Sorts chunks by C
+      sorted_chunks = qr_chunks.sort_by { |c| c[%r{/(.*?)/}, 1].to_i }
+      # Strip prefix
+      sorted_chunks.map { |c| c.sub(%r{shc:/(.*?)/(.*?)/}, '') }
+    end
+  end
+end

data/lib/health_cards/covid_health_card.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module HealthCards
+  # Implements HealthCard for use with COVID Vaccination IG
+  class COVIDHealthCard < HealthCards::HealthCard
+    fhir_version '4.0.1'
+    additional_types 'https://smarthealth.cards#covid19'
+
+    allow FHIR::Patient, %w[name birthDate]
+    allow FHIR::Immunization, %w[status vaccineCode patient occurrenceDateTime]
+  end
+end

data/lib/health_cards/encoding.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'base64'
+
+module HealthCards
+  # Encoding utilities for producing JWS
+  #
+  # @see https://datatracker.ietf.org/doc/html/rfc7515#appendix-A.3.1
+  module Encoding
+    # Encodes the provided data using url safe base64 without padding
+    # @param data [String] the data to be encoded
+    # @return [String] the encoded data
+    def encode(data)
+      Base64.urlsafe_encode64(data, padding: false).gsub("\n", '')
+    end
+
+    # Decodes the provided data using url safe base 64
+    # @param data [String] the data to be decoded
+    # @return [String] the decoded data
+    def decode(data)
+      Base64.urlsafe_decode64(data)
+    end
+  end
+end

data/lib/health_cards/exceptions.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module HealthCards
+  # Exception thrown when a private key is expected or required
+  class MissingPrivateKey < StandardError
+    def initialize(msg = 'Missing private key')
+      super(msg)
+    end
+  end
+
+  # Exception thrown when a public key is expected or required
+  class MissingPublicKey < StandardError
+    def initialize(msg = 'Missing public key')
+      super(msg)
+    end
+  end
+
+  # Exception thrown when an invalid payload is provided
+  class InvalidPayloadException < ArgumentError
+    def initialize(msg = 'Bundle must be a FHIR::Bundle')
+      super(msg)
+    end
+  end
+
+  # Exception thrown when verifiable credential JSON does not include a locatable FHIR Bundle
+  class InvalidCredentialException < ArgumentError
+    def initialize(msg = 'Unable to locate FHIR Bundle in credential')
+      super(msg)
+    end
+  end
+
+  # Exception thrown when an invalid key (public or private) is provided
+  class InvalidKeyException < ArgumentError
+    def initialize(expected_class, actual_obj)
+      super("Expected an instance of #{expected_class} but was #{actual_obj.class}")
+    end
+  end
+
+  # Exception thrown when a reference in a bundle in unresolvable
+  class InvalidBundleReferenceException < ArgumentError
+    def initialize(url)
+      super("Unable to resolve url (#{url}) within bundle")
+    end
+  end
+end

data/lib/health_cards/exporter.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module HealthCards
+  # Converts a JWS to formats needed by endpoints (e.g. $issue-health-card, download and qr code)
+  module Exporter
+    extend Chunking
+
+    # Export JWS for file download
+    # @param [Array<JWS, String>] An array of JWS objects to be exported
+    # @return [String] JSON string containing file download contents
+    def self.download(jws)
+      { verifiableCredential: jws.map(&:to_s) }.to_json
+    end
+
+    # Export JWS for $issue-health-card endpoint
+    # @param [Array<WJS, String] An array of JWS objects to be exported
+    # @return [String] JSON string containing a FHIR Parameters resource
+    def self.issue(jws)
+      params = jws.map { |j| FHIR::Parameters::Parameter.new(name: 'verifiableCredential', valueString: j) }
+      FHIR::Parameters.new(parameter: params).to_json
+    end
+  end
+end

data/lib/health_cards/health_card.rb

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+require 'json/minify'
+require 'zlib'
+
+module HealthCards
+  # A HealthCard which implements the credential claims specified by https://smarthealth.cards/
+  class HealthCard
+    VC_TYPE = [
+      'https://healthwallet.cards#health-card'
+    ].freeze
+
+    attr_reader :issuer, :nbf, :bundle
+
+    class << self
+      # Creates a HealthCard from a JWS
+      # @param jws [String] the JWS string
+      # @param public_key [HealthCards::PublicKey] the public key associated with the JWS
+      # @param key [HealthCards::PrivateKey] the private key associated with the JWS
+      # @return [HealthCards::HealthCard]
+      def from_jws(jws, public_key: nil, key: nil)
+        jws = JWS.from_jws(jws, public_key: public_key, key: key)
+        from_payload(jws.payload)
+      end
+
+      # Create a HealthCard from a compressed payload
+      # @param payload [String]
+      # @return [HealthCards::HealthCard]
+      def from_payload(payload)
+        json = decompress_payload(payload)
+        bundle_hash = json.dig('vc', 'credentialSubject', 'fhirBundle')
+
+        raise HealthCards::InvalidCredentialException unless bundle_hash
+
+        bundle = FHIR::Bundle.new(bundle_hash)
+        new(issuer: json['iss'], bundle: bundle)
+      end
+
+      # Decompress an arbitrary payload, useful for debugging
+      # @param payload [String] compressed payload
+      # @return [Hash] Hash built from JSON contents of payload
+      def decompress_payload(payload)
+        inf = Zlib::Inflate.new(-Zlib::MAX_WBITS).inflate(payload)
+        JSON.parse(inf)
+      end
+
+      # Compress an arbitrary payload, useful for debugging
+      # @param payload [Object] Any object that responds to to_s
+      # @return A compressed version of that payload parameter
+      def compress_payload(payload)
+        Zlib::Deflate.new(nil, -Zlib::MAX_WBITS).deflate(payload.to_s, Zlib::FINISH)
+      end
+
+      # Define allowed attributes for this HealthCard class
+      # @param klass [Class] Scopes the attributes to a spefic class. Must be a subclass of FHIR::Model
+      # @param attributes [Array] An array of string with the attribute names that will be passed through
+      #  when data is minimized
+      def allow(klass, attributes)
+        resource_type = klass.name.split('::').last
+        allowable[resource_type] = attributes
+      end
+
+      # Define allowed attributes for this HealthCard class
+      # @return [Hash] A hash of FHIR::Model subclasses and attributes that will pass through minimization
+      def allowable
+        @allowable ||= {}
+      end
+
+      # Sets/Gets the fhir version that will be passed through to the credential created by an instnace of
+      # this HealthCard (sub)class
+      # @param ver [String] FHIR Version supported by this HealthCard (sub)class. Leaving this param out
+      # will only return the current value
+      # value (used as a getter)
+      # @return [String] Current FHIR version supported
+      def fhir_version(ver = nil)
+        @fhir_version ||= ver unless ver.nil?
+        @fhir_version
+      end
+
+      # Additional type claims this HealthCard class supports
+      # @param types [String, Array] A string or array of string representing the additional type claims or nil
+      # if used as a getter
+      # @return [Array] the additional types added by this classes
+      def additional_types(*add_types)
+        types.concat(add_types) unless add_types.nil?
+        types - VC_TYPE
+      end
+
+      # Type claims supported by this HealthCard subclass
+      # @return [Array] an array of Strings with all the supported type claims
+      def types
+        @types ||= VC_TYPE.dup
+      end
+
+      # Check if this class supports the given type claim(s)
+      # @param type [Array, String] A type as defined by the SMART Health Cards framework
+      # @return [Boolean] Whether or not the type param is included in the types supported by the HealthCard (sub)class
+      def supports_type?(*type)
+        !types.intersection(type).empty?
+      end
+    end
+
+    # Create a HealthCard
+    #
+    # @param bundle [FHIR::Bundle] VerifiableCredential containing a fhir bundle
+    # @param issuer [String] The url from the Issuer of the HealthCard
+    def initialize(bundle:, issuer: nil)
+      raise InvalidPayloadException unless bundle.is_a?(FHIR::Bundle)
+
+      @issuer = issuer
+      @bundle = bundle
+    end
+
+    # A Hash matching the VC structure specified by https://smarthealth.cards/#health-cards-are-encoded-as-compact-serialization-json-web-signatures-jws
+    # @return [Hash]
+    def to_hash
+      {
+        iss: issuer,
+        nbf: Time.now.to_i,
+        vc: {
+          type: self.class.types,
+          credentialSubject: {
+            fhirVersion: self.class.fhir_version,
+            fhirBundle: strip_fhir_bundle
+          }
+        }
+
+      }
+    end
+
+    # A compressed version of the FHIR::Bundle based on the SMART Health Cards frame work and any other constraints
+    # defined by a subclass
+    # @return String compressed payload
+    def to_s
+      HealthCard.compress_payload(to_json)
+    end
+
+    # A minified JSON string matching the VC structure specified by https://smarthealth.cards/#health-cards-are-encoded-as-compact-serialization-json-web-signatures-jws
+    # @return [String] JSON string
+    def to_json(*_args)
+      JSON.minify(to_hash.to_json)
+    end
+
+    # Processes the bundle according to https://smarthealth.cards/#health-cards-are-small and returns
+    # a Hash with equivalent values
+    # @return [Hash] A hash with the same content as the FHIR::Bundle, processed accoding
+    # to SMART Health Cards framework and any constraints created by subclasses
+    def strip_fhir_bundle
+      stripped_bundle = @bundle.to_hash
+      if stripped_bundle.key?('entry') && !stripped_bundle['entry'].empty?
+        entries = stripped_bundle['entry']
+        entries, @url_map = redefine_uris(entries)
+        update_elements(entries)
+      end
+      stripped_bundle
+    end
+
+    private
+
+    def redefine_uris(entries)
+      url_map = {}
+      resource_count = 0
+      entries.each do |entry|
+        old_url = entry['fullUrl']
+        new_url = "resource:#{resource_count}"
+        url_map[old_url] = new_url
+        entry['fullUrl'] = new_url
+        resource_count += 1
+      end
+      [entries, url_map]
+    end
+
+    def update_elements(entries)
+      entries.each do |entry|
+        resource = entry['resource']
+
+        resource.delete('id')
+        resource.delete('text')
+        if resource.dig('meta', 'security')
+          resource['meta'] = resource['meta'].slice('security')
+        else
+          resource.delete('meta')
+        end
+        handle_allowable(resource)
+        update_nested_elements(resource)
+      end
+    end
+
+    def handle_allowable(resource)
+      allowable = self.class.allowable[resource['resourceType']]
+      return resource unless allowable
+
+      allow = allowable + ['resourceType']
+      resource.select! { |att| allow.include?(att) }
+    end
+
+    def process_url(url)
+      new_url = @url_map.key?(url) ? @url_map[url] : @url_map["#{issuer}/#{url}"]
+      raise InvalidBundleReferenceException, url unless new_url
+
+      new_url
+    end
+
+    def update_nested_elements(hash)
+      hash.map { |k, v| update_nested_element(hash, k, v) }
+    end
+
+    def update_nested_element(hash, attribute_name, value) # rubocop:disable Metrics/CyclomaticComplexity
+      case value
+      when String
+        hash[attribute_name] = process_url(value) if attribute_name == 'reference'
+      when Hash
+        value.delete('text') if attribute_name.include?('CodeableConcept') || value.key?('coding')
+        update_nested_elements(value)
+      when Array
+        value.each do |member_element|
+          member_element.delete('display') if attribute_name == 'coding'
+          update_nested_elements(member_element) if member_element.is_a?(Hash)
+        end
+      end
+    end
+  end
+end

data/lib/health_cards/importer.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module HealthCards
+  # Converts a JWS to formats needed by endpoints (e.g. $issue-health-card, download and qr code)
+  module Importer
+    extend Chunking
+
+    # Import JWS from file upload
+    # @param  [String] JSON string containing file upload contents
+    # @return [Array<JWS>] An array of JWS objects
+    def self.upload(jws_string)
+      vc = JSON.parse(jws_string)
+      vc_jws = vc['verifiableCredential']
+      vc_jws.map do |j|
+        jws = JWS.from_jws(j)
+        HealthCard.decompress_payload(jws.payload)
+      end
+    end
+
+    def self.scan(qr_contents)
+      contents = JSON.parse(qr_contents)
+      get_payload_from_qr contents
+    end
+  end
+end

data/lib/health_cards/issuer.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require 'fhir_models'
+
+module HealthCards
+  # Issue Health Cards based on a stored private key
+  class Issuer
+    attr_reader :url, :key
+
+    # Create an Issuer
+    #
+    # @param key [HealthCards::PrivateKey] the private key used for signing issued health cards
+    def initialize(key:, url: nil)
+      @url = url
+      PrivateKey.enforce_valid_key_type!(key)
+      self.key = key
+    end
+
+    # Create a HealthCard from the supplied FHIR bundle
+    #
+    # @param bundle [FHIR::Bundle, String] the FHIR bundle used as the Health Card payload
+    # @return [HealthCard::]
+    def create_health_card(bundle, type: HealthCard)
+      type.new(issuer: url, bundle: bundle)
+    end
+
+    # Create a JWS for a given payload
+    #
+    # @param bundle [FHIR::Bundle] A FHIR::Bundle that will form the payload of the JWS object
+    # @param type [Class] A subclass of HealthCards::Card that processes the bundle according to a specific IG.
+    # Leave blank for default SMART Health Card behavior
+    # @return [HealthCards::JWS] An instance of JWS using the payload and signed by the issuer's private key
+    def issue_jws(bundle, type: HealthCard)
+      card = create_health_card(bundle, type: type)
+      JWS.new(header: jws_header, payload: card.to_s, key: key)
+    end
+
+    # Set the private key used for signing issued health cards
+    #
+    # @param key [HealthCards::PrivateKey, nil] the private key used for signing issued health cards
+    def key=(key)
+      PrivateKey.enforce_valid_key_type!(key)
+
+      @key = key
+    end
+
+    # Returns the public key matching this issuer's
+    # private key as a JWK KeySet JSON string useful for .well-known endpoints
+    # @return [String] JSON string in JWK standard
+    def to_jwk
+      KeySet.new(key.public_key).to_jwk
+    end
+
+    private
+
+    def jws_header
+      { 'zip' => 'DEF', 'alg' => 'ES256', 'kid' => key.public_key.kid }
+    end
+  end
+end

data/lib/health_cards/jws.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module HealthCards
+  # Create JWS from a payload
+  class JWS
+    class << self
+      include Encoding
+
+      # Creates a Card from a JWS
+      # @param jws [String, HealthCards::JWS] the JWS string
+      # @param public_key [HealthCards::PublicKey] the public key associated with the JWS
+      # @param key [HealthCards::PrivateKey] the private key associated with the JWS
+      # @return [HealthCards::HealthCard]
+      def from_jws(jws, public_key: nil, key: nil)
+        unless jws.is_a?(HealthCards::JWS) || jws.is_a?(String)
+          raise ArgumentError,
+                'Expected either a HealthCards::JWS or String'
+        end
+
+        header, payload, signature = jws.to_s.split('.').map { |entry| decode(entry) }
+        header = JSON.parse(header)
+        JWS.new(header: header, payload: payload, signature: signature,
+                public_key: public_key, key: key)
+      end
+    end
+
+    attr_reader :key, :public_key, :payload
+    attr_writer :signature
+    attr_accessor :header
+
+    # Create a new JWS
+
+    def initialize(header: nil, payload: nil, signature: nil, key: nil, public_key: nil)
+      # Not using accessors because they reset the signature which requires both a key and a payload
+      @header = header
+      @payload = payload
+      @signature = signature if signature
+      @key = key
+      @public_key = public_key || key&.public_key
+    end
+
+    # The kid value from the JWS header, used to identify the key to use to verify
+    # @return [String]
+    def kid
+      header['kid']
+    end
+
+    # Set the private key used for signing issued health cards
+    #
+    # @param key [HealthCards::PrivateKey, nil] the private key used for signing issued health cards
+    def key=(key)
+      PrivateKey.enforce_valid_key_type!(key, allow_nil: true)
+
+      @key = key
+
+      # If it's a new private key then the public key and signature should be updated
+      return if @key.nil?
+
+      reset_signature
+      self.public_key = @key.public_key
+    end
+
+    # Set the public key used for signing issued health cards
+    #
+    # @param public_key [HealthCards::PublicKey, nil] the private key used for signing issued health cards
+    def public_key=(public_key)
+      PublicKey.enforce_valid_key_type!(public_key, allow_nil: true)
+
+      @public_key = public_key
+    end
+
+    # Set the JWS payload. Setting a new payload will result in the a new signature
+    # @param new_payload [Object]
+    def payload=(new_payload)
+      @payload = new_payload
+      reset_signature
+    end
+
+    # The signature component of the card
+    #
+    # @return [String] the unencoded signature
+    def signature
+      return @signature if @signature
+
+      raise MissingPrivateKey unless key
+
+      @signature ||= key.sign(jws_signing_input)
+    end
+
+    # Export the card to a JWS String
+    # @return [String] the JWS
+    def to_s
+      [JSON.generate(header), payload, signature].map { |entry| JWS.encode(entry) }.join('.')
+    end
+
+    # Verify the digital signature on the jws
+    #
+    # @return [Boolean]
+    def verify
+      raise MissingPublicKey unless public_key
+
+      public_key.verify(jws_signing_input, signature)
+    end
+
+    private
+
+    def jws_signing_input
+      "#{JWS.encode(@header.to_json)}.#{encoded_payload}"
+    end
+
+    def encoded_payload
+      JWS.encode(payload)
+    end
+
+    # Resets the signature
+    #
+    # This method is primarily used when an attribute that affects
+    # the signature is changed (e.g. the private key changes, the payload changes)
+    def reset_signature
+      @signature = nil
+      signature if key && payload
+    end
+  end
+end

data/lib/health_cards/key.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require 'openssl'
+require 'base64'
+
+module HealthCards
+  # Methods to generate signing keys and jwk
+  class Key
+    BASE = { kty: 'EC', crv: 'P-256' }.freeze
+    DIGEST = OpenSSL::Digest.new('SHA256')
+
+    # Checks if obj is the the correct key type or nil
+    # @param obj Object that should be of same type as caller or nil
+    # @param allow_nil Allow/Disallow key to be nil
+    def self.enforce_valid_key_type!(obj, allow_nil:  false)
+      raise InvalidKeyException.new(self, obj) unless obj.is_a?(self) || (allow_nil && obj.nil?)
+    end
+
+    # Create a key from a JWK
+    #
+    # @param jwk_key [Hash] The JWK represented by a Hash
+    # @return [HealthCards::Key] The key represented by the JWK
+    def self.from_jwk(jwk_key)
+      jwk_key = jwk_key.transform_keys(&:to_sym)
+      group = OpenSSL::PKey::EC::Group.new('prime256v1')
+      key = OpenSSL::PKey::EC.new(group)
+      key.private_key = OpenSSL::BN.new(Base64.urlsafe_decode64(jwk_key[:d]), 2) if jwk_key[:d]
+      public_key_bn = ['04'].pack('H*') + Base64.urlsafe_decode64(jwk_key[:x]) + Base64.urlsafe_decode64(jwk_key[:y])
+      key.public_key = OpenSSL::PKey::EC::Point.new(group, OpenSSL::BN.new(public_key_bn, 2))
+      key.private_key? ? HealthCards::PrivateKey.new(key) : HealthCards::PublicKey.new(key)
+    end
+
+    def initialize(ec_key)
+      @key = ec_key
+    end
+
+    def group
+      @key.group
+    end
+
+    def to_json(*_args)
+      to_jwk.to_json
+    end
+
+    def to_jwk
+      coordinates.merge(kid: kid, use: 'sig', alg: 'ES256')
+    end
+
+    def kid
+      Base64.urlsafe_encode64(DIGEST.digest(public_coordinates.to_json), padding: false)
+    end
+
+    def public_coordinates
+      coordinates.slice(:crv, :kty, :x, :y)
+    end
+
+    def coordinates
+      return @coordinates if @coordinates
+
+      key_binary = @key.public_key.to_bn.to_s(2)
+      coords = { x: key_binary[1, key_binary.length / 2],
+                 y: key_binary[key_binary.length / 2 + 1, key_binary.length] }
+      coords[:d] = @key.private_key.to_s(2) if @key.private_key?
+      @coordinates = coords.transform_values do |val|
+        Base64.urlsafe_encode64(val, padding: false)
+      end.merge(BASE)
+    end
+  end
+end

data/lib/health_cards/key_set.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+
+module HealthCards
+  # A set of keys used for signing or verifying HealthCards
+  class KeySet
+    extend Forwardable
+
+    def_delegator :keys, :empty?
+
+    # Create a KeySet from a JWKS
+    #
+    # @param jwks [String] the JWKS as a string
+    # @return [HealthCards::KeySet]
+    def self.from_jwks(jwks)
+      jwks = JSON.parse(jwks)
+      keys = jwks['keys'].map { |jwk| HealthCards::Key.from_jwk(jwk) }
+      KeySet.new(keys)
+    end
+
+    # Create a new KeySet
+    #
+    # @param keys [HealthCards::Key, Array<HealthCards::Key>, nil] the initial keys
+    def initialize(keys = nil)
+      @key_map = {}
+      add_keys(keys) unless keys.nil?
+    end
+
+    # The contained keys
+    #
+    # @return [Array]
+    def keys
+      @key_map.values
+    end
+
+    # Returns the keys as a JWK
+    #
+    # @return JSON string in JWK format
+    def to_jwk
+      { keys: keys.map(&:to_jwk) }.to_json
+    end
+
+    # Retrieves a key from the keyset with a kid
+    # that matches the parameter
+    # @param kid [String] a Base64 encoded kid from a JWS or Key
+    # @return [HealthCard::Key] a key with a matching kid or nil if not found
+    def find_key(kid)
+      @key_map[kid]
+    end
+
+    # Add keys to KeySet
+    #
+    # Keys are added based on the key kid
+    #
+    # @param new_keys [HealthCards::Key, Array<HealthCards::Key>, HealthCards::KeySet] the initial keys
+    def add_keys(new_keys)
+      if new_keys.is_a? KeySet
+        add_keys(new_keys.keys)
+      else
+        [*new_keys].each { |new_key| @key_map[new_key.kid] = new_key }
+      end
+    end
+
+    # Remove keys from KeySet
+    #
+    # Keys are remove based on the key kid
+    #
+    # @param new_keys [HealthCards::Key, Array<HealthCards::Key>, HealthCards::KeySet] the initial keys
+    def remove_keys(removed_keys)
+      if removed_keys.is_a? KeySet
+        remove_keys(removed_keys.keys)
+      else
+        [*removed_keys].each { |removed_key| @key_map.delete(removed_key.kid) }
+      end
+    end
+
+    # Check if key is included in the KeySet
+    #
+    # @param key [HealthCards::Key]
+    # @return [Boolean]
+    def include?(key)
+      !@key_map[key.kid].nil?
+    end
+  end
+end

data/lib/health_cards/private_key.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module HealthCards
+  # A key used for signing JWS
+  class PrivateKey < Key
+    def self.from_file(path)
+      pem = OpenSSL::PKey::EC.new(File.read(path))
+      PrivateKey.new(pem)
+    end
+
+    def self.load_from_or_create_from_file(path)
+      if File.exist?(path)
+        from_file(path)
+      else
+        generate_key(file_path: path)
+      end
+    end
+
+    def self.generate_key(file_path: nil)
+      key = OpenSSL::PKey::EC.generate('prime256v1')
+      File.write(file_path, key.to_pem) if file_path
+      PrivateKey.new(key)
+    end
+
+    def sign(payload)
+      asn1_to_raw(@key.sign(OpenSSL::Digest.new('SHA256'), payload), self)
+    end
+
+    def public_key
+      return @public_key if @public_key
+
+      pub = OpenSSL::PKey::EC.new('prime256v1')
+      pub.public_key = @key.public_key
+      @public_key = PublicKey.new(pub)
+    end
+
+    private
+
+    # Convert the ASN.1 Representation into the raw signature
+    #
+    # Adapted from ruby-jwt and json-jwt gems. More info here:
+    # https://github.com/nov/json-jwt/issues/21
+    # https://github.com/jwt/ruby-jwt/pull/87
+    # https://github.com/jwt/ruby-jwt/issues/84
+    def asn1_to_raw(signature, private_key)
+      byte_size = (private_key.group.degree + 7) / 8
+      OpenSSL::ASN1.decode(signature).value.map { |value| value.value.to_s(2).rjust(byte_size, "\x00") }.join
+    end
+  end
+end

data/lib/health_cards/public_key.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module HealthCards
+  # A key used for verifying JWS
+  class PublicKey < Key
+    def self.from_json(json)
+      # TODO
+    end
+
+    def verify(payload, signature)
+      @key.verify(OpenSSL::Digest.new('SHA256'), raw_to_asn1(signature, self), payload)
+    end
+
+    private
+
+    # Convert the raw signature into the ASN.1 Representation
+    #
+    # Adapted from ruby-jwt and json-jwt gems. More info here:
+    # https://github.com/nov/json-jwt/issues/21
+    # https://github.com/jwt/ruby-jwt/pull/87
+    # https://github.com/jwt/ruby-jwt/issues/84
+    def raw_to_asn1(signature, key)
+      byte_size = (key.group.degree + 7) / 8
+      sig_bytes = signature[0..(byte_size - 1)]
+      sig_char = signature[byte_size..] || ''
+      OpenSSL::ASN1::Sequence.new([sig_bytes, sig_char].map do |int|
+        OpenSSL::ASN1::Integer.new(OpenSSL::BN.new(int, 2))
+      end).to_der
+    end
+  end
+end

data/lib/health_cards/verification.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module HealthCards
+  # Logic for verifying a HealthCard JWS
+  module Verification
+    # Verify Health Card with given KeySet
+    #
+    # @param verifiable [HealthCards::JWS, String] the health card to verify
+    # @param key_set [HealthCards::KeySet, nil] the KeySet from which keys should be taken or added
+    # @param resolve_keys [Boolean] if keys should be resolved
+    # @return [Boolean]
+    def verify_using_key_set(verifiable, key_set = nil, resolve_keys: true)
+      jws = JWS.from_jws(verifiable)
+      key_set ||= HealthCards::KeySet.new
+      key_set.add_keys(resolve_key(jws)) if resolve_keys && key_set.find_key(jws.kid).nil?
+
+      key = key_set.find_key(jws.kid)
+      raise MissingPublicKey, 'Verifier does not contain public key that is able to verify this signature' unless key
+
+      jws.public_key = key
+      jws.verify
+    end
+
+    # Resolve a key
+    # @param jws [HealthCards::JWS, String] The JWS for which to resolve keys
+    # @return [HealthCards::KeySet]
+    def resolve_key(jws)
+      res = Net::HTTP.get(URI("#{HealthCard.from_jws(jws.to_s).issuer}/.well-known/jwks.json"))
+      HealthCards::KeySet.from_jwks(res)
+    end
+  end
+end

data/lib/health_cards/verifier.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require_relative 'verification'
+
+module HealthCards
+  # Verifiers can validate HealthCards using public keys
+  class Verifier
+    attr_reader :keys
+    attr_accessor :resolve_keys
+
+    include HealthCards::Verification
+    extend HealthCards::Verification
+
+    # Verify a HealthCard
+    #
+    # This method _always_ uses key resolution and does not depend on any cached keys
+    #
+    # @param verifiable [HealthCards::JWS, String] the health card to verify
+    # @return [Boolean]
+    def self.verify(verifiable)
+      verify_using_key_set(verifiable)
+    end
+
+    # Create a new Verifier
+    #
+    # @param keys [HealthCards::KeySet, HealthCards::Key, nil] keys to use when verifying Health Cards
+    # @param resolve_keys [Boolean] Enables or disables key resolution
+    def initialize(keys: nil, resolve_keys: true)
+      @keys = case keys
+              when KeySet
+                keys
+              when Key
+                KeySet.new(keys)
+              else
+                KeySet.new
+              end
+
+      self.resolve_keys = resolve_keys
+    end
+
+    # Add a key to use when verifying
+    #
+    # @param key [HealthCards::Key, HealthCards::KeySet] the key to add
+    def add_keys(key)
+      @keys.add_keys(key)
+    end
+
+    # Remove a key to use when verifying
+    #
+    # @param key [HealthCards::Key] the key to remove
+    def remove_keys(key)
+      @keys.remove_keys(key)
+    end
+
+    # Verify a HealthCard
+    #
+    # @param verifiable [HealthCards::JWS, String] the health card to verify
+    # @return [Boolean]
+    def verify(verifiable)
+      verify_using_key_set(verifiable, keys, resolve_keys: resolve_keys?)
+    end
+
+    def resolve_keys?
+      resolve_keys
+    end
+  end
+end

data/lib/health_cards/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module HealthCards
+  VERSION = '0.0.1'
+end

metadata

@@ -0,0 +1,92 @@
+--- !ruby/object:Gem::Specification
+name: health_cards
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Reece Adamson
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2021-05-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: fhir_models
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: json-minify
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Create SMART Health Cards
+email:
+- radamson@mitre.org
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- lib/health_cards.rb
+- lib/health_cards/chunking.rb
+- lib/health_cards/covid_health_card.rb
+- lib/health_cards/encoding.rb
+- lib/health_cards/exceptions.rb
+- lib/health_cards/exporter.rb
+- lib/health_cards/health_card.rb
+- lib/health_cards/importer.rb
+- lib/health_cards/issuer.rb
+- lib/health_cards/jws.rb
+- lib/health_cards/key.rb
+- lib/health_cards/key_set.rb
+- lib/health_cards/private_key.rb
+- lib/health_cards/public_key.rb
+- lib/health_cards/verification.rb
+- lib/health_cards/verifier.rb
+- lib/health_cards/version.rb
+homepage: https://github.com/dvci/health-cards
+licenses:
+- Apache 2.0
+metadata:
+  homepage_uri: https://github.com/dvci/health-cards
+  source_code_uri: https://github.com/dvci/health_cards
+  changelog_uri: https://github.com/dvci/health_cards/CHANGELOG.md
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.15
+signing_key: 
+specification_version: 4
+summary: Create SMART Health Cards
+test_files: []