feat: make smartHandler more configurable (#24)

CODE_OF_CONDUCT.md

@@ -1,5 +1,3 @@
 ## Code of Conduct
 
-This project has adopted the [Amazon Open Source Code of Conduct](https://aws.github.io/code-of-conduct).
-For more information see the [Code of Conduct FAQ](https://aws.github.io/code-of-conduct-faq) or contact
-opensource-codeofconduct@amazon.com with any additional questions or comments.
+This project has adopted the [Amazon Open Source Code of Conduct](https://aws.github.io/code-of-conduct). For more information see the [Code of Conduct FAQ](https://aws.github.io/code-of-conduct-faq) or contact opensource-codeofconduct@amazon.com with any additional questions or comments.

CONTRIBUTING.md

@@ -1,17 +1,14 @@
 # Contributing Guidelines
 
-Thank you for your interest in contributing to our project. Whether it's a bug report, new feature, correction, or additional
-documentation, we greatly value feedback and contributions from our community.
+Thank you for your interest in contributing to our project. Whether it's a bug report, new feature, correction, or additional documentation, we greatly value feedback and contributions from our community.
 
-Please read through this document before submitting any issues or pull requests to ensure we have all the necessary
-information to effectively respond to your bug report or contribution.
+Please read through this document before submitting any issues or pull requests to ensure we have all the necessary information to effectively respond to your bug report or contribution.
 
 ## Reporting Bugs/Feature Requests
 
 We welcome you to use the GitHub issue tracker to report bugs or suggest features.
 
-When filing an issue, please check existing open, or recently closed, issues to make sure somebody else hasn't already
-reported the issue. Please try to include as much information as you can. Details like these are incredibly useful:
+When filing an issue, please check existing open, or recently closed, issues to make sure somebody else hasn't already reported the issue. Please try to include as much information as you can. Details like these are incredibly useful:
 
 - A reproducible test case or series of steps
 - The version of our code being used
@@ -35,18 +32,15 @@ To send us a pull request, please:
 5. Send us a pull request, answering any default questions in the pull request interface.
 6. Pay attention to any automated CI failures reported in the pull request, and stay involved in the conversation.
 
-GitHub provides additional document on [forking a repository](https://help.github.com/articles/fork-a-repo/) and
-[creating a pull request](https://help.github.com/articles/creating-a-pull-request/).
+GitHub provides additional document on [forking a repository](https://help.github.com/articles/fork-a-repo/) and [creating a pull request](https://help.github.com/articles/creating-a-pull-request/).
 
 ## Finding contributions to work on
 
 Looking at the existing issues is a great way to find something to contribute on. As our projects, by default, use the default GitHub issue labels (enhancement/bug/duplicate/help wanted/invalid/question/wontfix), looking at any 'help wanted' issues is a great place to start.
 
 ## Code of Conduct
 
-This project has adopted the [Amazon Open Source Code of Conduct](https://aws.github.io/code-of-conduct).
-For more information see the [Code of Conduct FAQ](https://aws.github.io/code-of-conduct-faq) or contact
-opensource-codeofconduct@amazon.com with any additional questions or comments.
+This project has adopted the [Amazon Open Source Code of Conduct](https://aws.github.io/code-of-conduct). For more information see the [Code of Conduct FAQ](https://aws.github.io/code-of-conduct-faq) or contact opensource-codeofconduct@amazon.com with any additional questions or comments.
 
 ## Security issue notifications
 

README.md

@@ -2,34 +2,109 @@
 
 ## Purpose
 
-Please visit [fhir-works-on-aws-deployment](https://github.com/awslabs/fhir-works-on-aws-deployment) for overall vision of the project and for more context.
+This package is an implementation of the authorization interface from the [FHIR Works interface](https://github.com/awslabs/fhir-works-on-aws-interface/blob/mainline/src/authorization.ts). It uses the [Substitutable Medical Applications, Reusable Technologies (SMART on FHIR) specification](https://docs.smarthealthit.org/) to authorize users. Requests are authorized by if the requestor or the patient in context is [**referenced**](https://www.hl7.org/fhir/references.html) in the resource in question.
 
-This package is an implementation of the authorization interface from the [FHIR Works interface](https://github.com/awslabs/fhir-works-on-aws-interface). It uses the [SMART on FHIR specification](https://docs.smarthealthit.org/) to authorize users and what they request.
+To use and deploy this component please follow the overall [`smart-mainline` branch README](https://github.com/awslabs/fhir-works-on-aws-deployment/tree/smart-mainline)
 
-To use and deploy this component (with the other 'out of the box' components) please follow the overall [README](https://github.com/awslabs/fhir-works-on-aws-deployment)
+## Assumptions
 
-## Infrastructure
-
-This package assumes certain infrastructure:
+The following assumptions have been made while creating this package:
 
 - An [OAuth2](https://oauth.net/2/) [OpenID Connect](https://openid.net/connect/) authorization server already exists and is used as or in conjunction with an identity provider.
-  - This server complies with the [SMART on FHIR specification](https://docs.smarthealthit.org/)
-- The identity provider has a user claim (either `fhirUser` or `profile`) representing who this user is in context to this EHR.
-  - For example if a user signs in and their `fhirUser` claim is `Patient/1234`. This means that Patient resource 1234 is the record of the signed in user.
+  - The OAuth2 server complies with the [SMART on FHIR specification](https://docs.smarthealthit.org/)
+  - The OAuth2 server has a JSON Web Key Set endpoint used to get the key for verifying incoming access token
+- The identity provider has a user claim (either `fhirUser` or `profile`) representing who this user is in context to this FHIR server. This user must be represented by a fully qualified URL in the claim.
+  - As an example the `fhirUser` claim should look like: `https://www.fhir.com/Patient/1234`
+  - When using `user` scopes it is assumed that the `fhirUser` will be in the access token to determine who the requestor is
+- [`launch` scopes and contextual request](http://www.hl7.org/fhir/smart-app-launch/scopes-and-launch-context/#scopes-for-requesting-context-data) will be handled by the authorization server.
+- Once launch context is given to the authorization server it will be included with a `patient` scope and the Patient's resourceType and id in the `launch_response_patient` claim within the access token.
+  - As an example the `launch_response_patient` claim should look like: `Patient/id`
+
+## Authorization
+
+This packages uses SMART scopes and the references found in the resources as a way to determine access. Scopes are used to tell the authorization and resource server what access the requestor has. In addition the references are used to do further authorization, in an attribute based access control model.
+
+### Scopes
+
+This resource server supports [SMART's clinical scopes](http://www.hl7.org/fhir/smart-app-launch/scopes-and-launch-context/#clinical-scope-syntax). There are some assumptions made on the authorization and resource server relationship:
+
+- For `patient` scopes, there must be a `launch_response_patient` claim in the access token.
+- For `user` scopes, there must be a `fhirUser` claim in the access token.
+- The access modifiers `read` and `write` will give permissions as defined in the incoming [SMARTConfig](./src/smartConfig.ts).
+
+### Attribute Based Access Control (ABAC)
+
+This implementation of the SMART on FHIR specification uses attribute based access control. Access to a resource is given if one of the following statements is true:
+
+- The fhirUser making the request is considered an Admin (default configuration makes a Practitioner an admin).
+- The fhirUser making the request or the patient in context looking up their own resource (verified via the `resourceType` and `id`).
+- The fhirUser making the request or the patient in context is referenced in the resource in which they are taking action on.
+
+As an example below, the Patient resource is accessible by:
+
+- Admins of the system
+- `Patient/example`: via `resourceType` and `id` check
+- `Patient/diffPatient`: since it is referenced in the `link` field
+- `Practitioner/DrBell`: since it is referenced in the `generalPractitioner` field
+
+```json
+// Example Patient pesource with references
+{
+  "resourceType": "Patient",
+  "id": "example",
+  "generalPractitioner": [
+    {
+      "reference": "Practitioner/DrBell"
+    }
+  ],
+  "link": [
+    {
+      "type": "seealso",
+      "other": {
+        "reference": "Patient/diffPatient"
+      }
+    }
+  ],
+  "address": [
+    {
+      "period": {
+        "start": "1974-12-25"
+      },
+      "city": "London",
+      "use": "home",
+      "line": ["221b Baker St"],
+      "district": "Marylebone",
+      "postalCode": "6XE",
+      "text": "221b Baker St, Marylebone, London NW1 6XE, United Kingdom",
+      "type": "both"
+    }
+  ],
+  "deceasedBoolean": false,
+  "name": [
+    {
+      "family": "Holmes",
+      "given": ["Sherlock"],
+      "use": "official"
+    }
+  ],
+  "gender": "male",
+  "active": true
+}
+```
 
 ## Usage
 
-For usage please add this package to your `package.json` file and install as a dependency. For usage examples please see the deployment component's [package.json](https://github.com/awslabs/fhir-works-on-aws-deployment/blob/authz-smart/package.json)
+Add this package to your `package.json` file and install as a dependency. For usage examples please see the deployment component's [package.json](https://github.com/awslabs/fhir-works-on-aws-deployment/blob/smart-mainline/package.json)
 
 ### Configuration
 
-This SMART implementation is meant to be flexible. It acheives this through the [SMARTConfig](./src/smartConfig.ts). This FHIR server knows the auhtorization server by the configuration defined as OauthStrategy in the [fhirConfig.ts](https://github.com/awslabs/fhir-works-on-aws-interface/blob/mainline/src/fhirConfig.ts).
+The SMART specification gives a lot of room for interpretation between the resource and authorization server relationship. With this in mind we developed our SMART implementation to be flexible. The configurations currently available can be viewed in the [SMARTConfig](./src/smartConfig.ts).
 
 ### SMART on FHIR scope rules
 
-Within the [SMARTConfig](./src/smartConfig.ts) you can see an example implementation of a ScopeRule. The ScopeRule lays what what operations a scope gives access to. For example for the `user/*.write` scope may give 'create' access but not 'update'.
+Within the [SMARTConfig](./src/smartConfig.ts) you can see an example implementation of a ScopeRule. The ScopeRule lays what operations a scope gives access to. For example, the `user/*.write` scope provides 'create' resource access but not 'update' resource.
 
-For a working example please see [authZConfig.ts](https://github.com/awslabs/fhir-works-on-aws-deployment/blob/authz-smart/src/authZConfig.ts) in the deployment package
+For an example usage of the SMARTConfig, please see [authZConfig.ts](https://github.com/awslabs/fhir-works-on-aws-deployment/blob/smart-mainline/src/authZConfig.ts) in the deployment package
 
 ## Dependency tree
 
@@ -40,7 +115,7 @@ This package is dependent on:
 
 ## Known issues
 
-For known issues please track the issues on the GitHub repository
+You can track the issues on the GitHub repository.
 
 ## Security