Pull in Court Changes

CODE_REVIEW.md

@@ -87,35 +87,31 @@ We wouldn’t want anyone being mean to us because of an oversight, mistake, or
 
 We use this list when performing a code review to ensure that all tasks have been completed.
 
+- [ ] begin by deleting any existing copy of the Git repository and cloning a fresh copy, and running `docker system prune` to remove any cached artifacts from any prior code review
 - [ ] review the pull request itself, to get oriented
 	- [ ] read the description of the pull request, which should summarize the changes made
 	- [ ] read through every task on the Scrum board that's encompassed by this pull request
-	- [ ] read the description of every commit that comprises the pull request
+	- [ ] read the description of the commits that comprise the pull request
 - [ ] stand up the site locally
 	- [ ] test all functionality in all major browsers, emphasizing the functionality that this pull request addresses
-		- [ ] perform the most thorough testing in Chrome and Internet Explorer 11, on Windows 7 and 10
-		- [ ] test in Edge and Firefox
-		- [ ] test in Mobile Safari and Mobile Chrome, with the caveat that not all functionality will be necessary on these platforms
+		- [ ] for internal Court functionality, perform the most thorough testing in Chrome, though also test in Edge and Firefox
+		- [ ] for public-facing functionality, test in browsers consistent with [public browser use data](https://analytics.usa.gov/), including Internet Explorer 11
+		- [ ] test in Mobile Safari and Mobile Chrome, with the caveat that not all internal Court functionality will be necessary on these platforms
 	- [ ] use an automated audit tool for code quality and practices (recommended: [Chrome DevTools](https://developers.google.com/web/tools/chrome-devtools/), aka [Lighthouse](https://chrome.google.com/webstore/detail/lighthouse/blipmdconlkpinefehnmjammfjpmpbjk))
 		- [ ] look at efficiency of page loads, asset sizes, HTTP connection management, etc.
 	- [ ] review for accessibility
 		- [ ] use an automated audit tool, such as Chrome Audit or aXe
 		- [ ] navigate site only with the keyboard
 		- [ ] use VoiceOver or Narrator to navigate the site with audio only, with the display turned off
 		- [ ] manually test anything that pa11y cannot test automatically (e.g., contrast of text over images)
-- [ ] review static code analysis results
-- [ ] examine OWASP ZAP output in `docs/`, ensure that any errors are known to be false positives or have been previously declared to be acceptable
-- [ ] critically read all new code, in the context of existing code, [looking for problems](#what-we-look-for), e.g.:
-	- [ ] make sure names of methods and variables are sensible
-	- [ ] make sure code does not contain secrets
-	- [ ] be suspicious of commented-out code
-	- [ ] any code with a purpose that isn’t immediately clear should have a comment explaining it
-	- [ ] check that code style is consistent
-	- [ ] be suspicious of any code that accepts input from the outside world, ensure that it doesn’t enable any kind of buffer overflows or SQL injection attacks
-- [ ] tests
+- [ ] review static code analysis results in SonarCloud
+- [ ] run a security audit of dependencies (`npm audit`) in `efcms-service`, `web-client`, and `shared`, to ensure that there are no vulnerabilities that will be deployed to production (as opposed to vulnerabilities that only have an impact on the development environment)
+- [ ] examine OWASP ZAP output in `docs/`, to ensure that any errors are known to be false positives or have been previously declared to be acceptable
+- [ ] skim all new code, in the context of existing code, [looking for problems](#what-we-look-for) (knowing that the vast majority of new code will be covered by tests)
+- [ ] review all tests
 	- [ ] look at code coverage of tests in SonarCloud
-	- [ ] review all new tests for correctness, quality of naming
-	- [ ] determine what code isn’t tested, review that especially carefully
+	- [ ] methodically review all new tests for correctness, quality of naming
+- [ ] determine what code isn’t tested, review that rigorously
 - [ ] review documentation to ensure that it matches changes
 - [ ] provide comments on the pull request on GitHub, as necessary
 	- [ ] for comments that are specific to a particular line of code, comment on those specific lines

README.md

@@ -79,9 +79,13 @@ Both the web-client and efcms-service share code that exists in the `shared` dir
 
 - `cd efcms-service && npm start`
 
-#### Login and Test Users
+## Login and Test Users
 
-- for /mock-login you can login using:
+There are two login mechanisms available — the legacy mock login system, and a new one that emulates AWS Cognito.
+
+## Mock Login
+
+You can log in using these usernames:
 
 ```
 taxpayer
@@ -92,30 +96,32 @@ respondent
 seniorattorney
 ```
 
-- to run the project locally using the dev cognito:
-  `npm run dev:cognito`
-  You can then login with:
+No password is required.
+
+## AWS Cognito 
+
+To run use Cognito, start the web client with `npm run dev:cognito` (instead of `npm start`) You can then log in with:
 
 ```
-petitioner1@example.com - petitioner5@example.com
-petitionsclerk1@example.com - petitionsclerk5@example.com
-docketclerk1@example.com - docketclerk5@example.com
-intakeclerk1@example.com - intakeclerk5@example.com
-respondent1@example.com - respondent5@example.com
-seniorattorney1@example.com - seniorattorney5@example.com
+petitioner1@example.com – petitioner5@example.com
+petitionsclerk1@example.com – petitionsclerk5@example.com
+docketclerk1@example.com – docketclerk5@example.com
+intakeclerk1@example.com – intakeclerk5@example.com
+respondent1@example.com – respondent5@example.com
+seniorattorney1@example.com – seniorattorney5@example.com
 ```
 
-all passwords are:
+The password for all accounts is:
 
 `Testing1234$`
 
-### CI/CD Setup
+## CI/CD Setup
 
 For instructions on how to build the DevOps pipeline and deploy the software to AWS, see [SETUP.md](SETUP.md).
 
-### Editor configuration
+## Editor configuration
 
-#### Atom.io
+### Atom.io
 
 Install the following for best results:
 

SETUP.md

@@ -22,6 +22,7 @@ The end result of this is not a dev, staging, or production website, but is inst
 - [Configure the AWS CLI account](https://docs.aws.amazon.com/cli/latest/userguide/cli-config-files.html) on your local machine to use the role or user you just created in IAM.
 - Clone this GitHub repository locally.
 - [Create a new GitHub account](https://github.com/join), with read-level access to the repository, which Jenkins will use to interact with GitHub. (GitHub describes these as “bot accounts” or “machine accounts,” and they are the exception to GitHub’s rule that accounts are intended for humans.)
+- [Create a GitHub personal access token](https://github.com/settings/tokens), which Jenkins will use to build pull requests. Give it the following permissions: `repo:status`, `public_repo`, `admin:repo_hook`, `write:repo_hook`, and `read:repo_hook`. (This will be referred to as `GITHUB_TOKEN` when setting up Jenkins.)
 - [Create a SonarCloud account](https://sonarcloud.io/). SonarCloud will be used to tests each build.
 - [Create a new SonarCloud organization](https://sonarcloud.io/create-organization).
   - [Create a token](https://sonarcloud.io/account/security) that Jenkins can use to interact with SonarCloud. (This will be referred to as `SONAR_TOKEN` when setting up Jenkins.)
@@ -46,37 +47,38 @@ The end result of this is not a dev, staging, or production website, but is inst
    - Note the values of the four `NS` domains. These are what need to be added to the DNS entry for your main domain name.
    - The method of modifying your main domain name’s DNS will vary enormously, so specific guidance is impossible, but you need to create four new `NS` records, one for each of those Route 53 records, with a host name of the subdomain (e.g., `ef-cms`) and a value of the AWS DNS (e.g., `ns-123.awsdns-56.net`). If you are limited in the number of `NS` records that you can create, simply create as many of the four as you can.
 6. If completing the prior step took more than a few minutes, then step 3 failed. That’s OK! Simply re-run `deploy-infrastructure.sh`.
-7. After `deploy-infrastructure.sh` has completed successfully, run the script to install plugins into Jenkins, `setup-jenkins.sh`, found in `management/bin/`.
+7. After `deploy-infrastructure.sh` has completed successfully, run the script to install plugins into Jenkins, `setup-jenkins.sh`, found in `management/bin/`. This must be run from within `management/management/`, like such: `../bin/setup-jenkins.sh`.
 8. Log into Jenkins.
    - Get the Jenkins credentials, using `show-passwords.sh`, found in `management/management/`.
    - Note the Jenkins username and password.
    - Open Jenkins in your browser. This is found on the subdomain that you figured, at the `jenkins-ef-cms-ops` sub-subdomain, and in the `/jenkins/` subdirectory, e.g. `https://jenkins-ef-cms-ops.ef-cms.example.gov/jenkins/`.
    - Click the `x` in the top right off the modal that appears.
      - You may be prompted to restart Jenkins, in which case you should do so.
      - After restarting, the modal will pop up again — just click the `x` again.
-9. Create 3 global credentials in Jenkins, so that Jenkins has permission to interact with GitHub and SonarCloud, using the credentials that you set up per [the prerequisites](#Prerequisites). This is done at a URL like `https://jenkins-ef-cms-ops.ef-cms.ustaxcourt.gov/jenkins/credentials/store/system/domain/_/`, which you can get to by choosing `Credentials` from the home page menu, `System` ⟶ `Global credentials` ⟶ `Add Credentials`.
+9. Create five global credentials in Jenkins, so that Jenkins has permission to interact with GitHub, SonarCloud, and AWS Cognito using the credentials that you set up per [the prerequisites](#Prerequisites). This is done at a URL like `https://jenkins-ef-cms-ops.ef-cms.ustaxcourt.gov/jenkins/credentials/store/system/domain/_/`, which you can get to by choosing `Credentials` from the home page menu, `System` ⟶ `Global credentials` ⟶ `Add Credentials`.
    - Create a “username with password” type. Provide an ID of `GITHUB_USER`, and enter the username and password for the GitHub account that you created.
    - Create a “secret text” type. Provide an ID of `API_SONAR_TOKEN`, and a `secret` that is the value of the token that you created in SonarCloud.
    - Create a “secret text” type. Provide an ID of `UI_SONAR_TOKEN`, and a `secret` that is the value of the token that you created in SonarCloud.
    - Create a “secret text” type. Provide an ID of `SHARED_SONAR_TOKEN`, and a `secret` that is the value of the token that you created in SonarCloud.
    - Create a “secret text” type. Provide an ID of `USTC_ADMIN_PASS`, and a `secret` of your choice.  When the deploy runs, a Cognito user with the email of 'ustcadmin@example.com' will be created with the password you supplied in `secret`.  This ustcadmin@example.com user is currently only used for hitting the POST@v1/users endpoint for creating users.
+   - Create a “secret text” type. Provide an ID of `GITHUB_TOKEN`, and a `secret` that is the value of the token that you created in GitHub.
 
 10. Set up the Sonar organization properties in Jenkins. This is done in `Jenkins` ⟶ `Manage Jenkins` ⟶ `Configure System` ⟶ `Global properties`, and then by checking off `Environment variables` to reveal the interface to add new variables. Add the following name/value pairs:
 
-- `SONAR_ORG` / your sonar organization’s name
-- `EFCMS_DOMAIN` / your subdomain, e.g. `ef-cms.example.gov`
-- `UI_SONAR_KEY` / your Sonar UI project key, e.g. `ef-cms-ui`
-- `API_SONAR_KEY` / your Sonar API project key, e.g. `ef-cms-api`
-- `SHARED_SONAR_KEY` / your Sonar API project key, e.g. `ef-cms-shared`
-- `COGNITO_SUFFIX` / your suffix to use for the Cognito URL, e.g. `flexion-efcms`
+    - `SONAR_ORG` / your sonar organization’s name
+    - `EFCMS_DOMAIN` / your subdomain, e.g. `ef-cms.example.gov`
+    - `UI_SONAR_KEY` / your Sonar UI project key, e.g. `ef-cms-ui`
+    - `API_SONAR_KEY` / your Sonar API project key, e.g. `ef-cms-api`
+    - `SHARED_SONAR_KEY` / your Sonar API project key, e.g. `ef-cms-shared`
+    - `COGNITO_SUFFIX` / your suffix to use for the Cognito URL, e.g. `flexion-efcms`
 
 11. At the CLI, set up the jobs via the `setup-jobs.sh` script, which is in `management/bin/`. This script takes three arguments, with a complete command like: `../bin/setup-jobs.sh https://github.com/flexion/ef-cms.git flexion ef-cms`. Those arguments are, in this order:
     - Your Git repository’s URL, e.g. `https://github.com/examplecourt/ef-cms.git`.
-
-- Your organization’s name in GitHub, e.g. `examplecourt`.
-- The project repository’s name in GitHub, e.g. `ef-cms`.
+    - Your organization’s name in GitHub, e.g. `examplecourt`.
+    - The project repository’s name in GitHub, e.g. `ef-cms`.
 
 12. Increase the number of Jenkins executors to five. Choose `Jenkins` ⟶ `Build Executor Status` ⟶ `Master` ⟶ `Configure`, and change `# of executors` from `2` to `5`.
 13. Restart Jenkins. This can be done by choosing `Jenkins` (i.e., going to the home page), and appending `safeRestart` to the URL, e.g. `https://jenkins-ef-cms-ops.ef-cms.example.gov/jenkins/safeRestart`.
+14. Set up Jenkins to build pull requests on GitHub. In the GitHub repository housing this project, [create a new webhook](https://github.com/ustaxcourt/ef-cms/settings/hooks). For the `Payload URL`, enter the Jenkins server URL with `/github-webhook/` appended, e.g. `https://jenkins-ef-cms-ops.ef-cms.example.gov/jenkins/github-webhook/`. Select a `Content type` of `application/x-www-form-urlencoded`, enable SSL verification, and send all events to trigger the webhook.
 
 You are done — the CI/CD pipeline is now ready to operate. To run a build, [see Jenkins documentation](https://jenkins.io/doc/).