Consent-Based Verification (CBV) is a prototype that allows benefit applicants to verify their income directly using payroll providers. It is currently being piloted for testing and validation purposes.

If you're new to Rails, see the Getting Started with Rails guide for an introduction to the framework.

1. Install Xcode Command Line Tools: xcode-select --install
2. Install homebrew dependencies: brew bundle
   • rbenv
   • nodenv
   • redis
   • jq
   • PostgreSQL
   • Dockerize
   • ADR Tools
   • Graphviz: brew install graphviz
   • Chromedriver
     • Chromedriver must be allowed to run. You can either do that by:
       • The command line: xattr -d com.apple.quarantine $(which chromedriver) (this is the only option if you are on Big Sur)
       • Manually: clicking "allow" when you run the integration tests for the first time and a dialogue opens up
   • Ngrok: brew install ngrok/ngrok/ngrok
     • Sign up for an account: https://dashboard.ngrok.com/signup
     • run ngrok config add-authtoken {token goes here}
3. Set up rbenv and nodenv:
   • echo 'if which nodenv >/dev/null 2>/dev/null; then eval "$(nodenv init -)"; fi' >> ~/.zshrc
   • echo 'if which rbenv >/dev/null 2>/dev/null; then eval "$(rbenv init -)"; fi' >> ~/.zshrc
   • Close & re-open your terminal

The following commands must be run in the app directory

1. Install Ruby: rbenv install
2. Install NodeJS nodenv install
3. Install Ruby dependencies: bundle install
   • If you get an error from debase, run this command: gem install debase -v0.2.5.beta2 -- --with-cflags="-Wno-incompatible-function-pointer-types"
   • Also we should probably fix this (TODO)
4. Install JS dependencies
   • nodenv rehash
   • npm install
5. Start postgres & redis:
   • brew services start postgresql@12
   • brew services start redis
6. Get development credentials from 1Password: search for "CBV Rails Secrets" and copy its ".env.development.local" section into a file called that in the app directory.
7. Create database: bin/rails db:create
8. Run migrations: bin/rails db:migrate
9. Run the development server: bin/dev
10. Visit the site: http://localhost:3000

Environment variables can be set in development using the dotenv gem.

Any changes to variables in .env that should not be checked into git should be set in .env.local.

If you wish to override a config globally for the test Rails environment you can set it in .env.test.local. However, any config that should be set on other machines should either go into .env or be explicitly set as part of the test.

To run locally, use bin/dev

When beginning work on a feature, create a new branch based off of main and make the commits for that feature there.

We intend to use short-lived branches so as to minimize the cost of integrating each feature into the main branch.

TBD

TBD

The system's Content-Security-Policy header prevents <script> and <style> tags from working without further configuration. Use <%= javascript_tag nonce: true %> for inline javascript.

We use the gem i18n-tasks to manage locale files. Here are a few common tasks:

Add missing keys across locales:

$ i18n-tasks missing # shows missing keys
$ i18n-tasks add-missing # adds missing keys across locale files

Key sorting:

$ i18n-tasks normalize

Removing unused keys:

$ i18n-tasks unused # shows unused keys
$ i18n-tasks remove-unused # removes unused keys across locale files

For more information on usage and helpful rake tasks to manage locale files, see the documentation.

The CBV pilot project is architected to be multi-tenant across jurisdictions we are actively piloting with. Each jurisdiction's agency is configured as a "site" in app/config/site-config.yml and has a short "id", e.g. "nyc", "ma", and "sandbox".

We often need to adjust copy specific to each site. The preferred way to do it is by using the site_translation helper, which wraps Rails's t view helper and looks for the current site's "id" as a sub-key of the given prefix.

Usage:

<%= site_translation(".learn_more_html") %>

And the corresponding locale file:

learn_more_html:
  nyc: Learn more about <strong>NYC Human Resources Administration</strong>
  ma: Learn more about <strong>Massachusetts Department of Transitional Assistance</strong>
  sandbox: Learn more about <strong>CBV Test Agency</strong>
  default: Learn more about <strong>Default Agency</strong>

Similar to Rails's t helper, the string will be marked HTML-safe if its key prefix ends with _html.

• Tests: bundle exec rake spec
• Ruby linter: bundle exec rake standard
• Accessibility scan: ./bin/pa11y-scan
• Dynamic security scan: ./bin/owasp-scan
• Ruby static security scan: bundle exec rake brakeman
• Ruby dependency checks: bundle exec rake bundler:audit
• JS dependency checks: bundle exec rake npm:audit

Run everything: bundle exec rake

If you're new to CBV, here's a summary of how to get started navigating the app.

1. First, contact someone on the team to get you set up to log in.
2. Follow the instructions in the Setup section to run locally, then go to localhost:3000/sandbox/sso
3. The beginning of the workflow is to act as a caseworker to create an invitation. Start by signing in with your Nava credentials.
4. Create an invitation for an applicant to start using the app (use any email, and don't worry -- it won't really send!)
5. In your terminal session, navigate to the /app directory and run rails c to enter the irb prompt.
6. At the irb prompt, run CbvFlowInvitation.last.to_url.
7. Click the resulting link. Now you're ready to start acting as an applicant!
8. Search for your employer. When you select one, the local page will show you some fake credentials at the very bottom of the screen. Use these to sign in.
9. Finally, you should be able to complete the applicant flow, including looking at the PDF.
10. To complete the caseworker flow, add ?is_caseworker=true to the /cbv/summary.pdf path to see the PDF that gets sent (it's different from the one we send the applicant!)
11. Note: You can switch to a different pilot partner (state) by going to the irb prompt and running CbvFlow.last.update(site_id: 'ma'). Right now you can only pass it ma or nyc.

When new pages are added to the application, ensure they are added to ./.pa11yci so that they can be scanned.

To enable automatic ruby linting and terraform formatting on every git commit follow the instructions at the top of .githooks/pre-commit

GitHub actions are used to run all tests and scans as part of pull requests.

Security scans are also run on a scheduled basis. Weekly for static code scans, and daily for dependency scans.

TK

This repo's main branch automatically deploys to our demo environment via a GitHub action.

To deploy to production, go to the repo's "Actions" tab on Github, click "Deploy App", and "Run Workflow".

TK

TK

The New Relic Ruby agent has been installed for monitoring this application.

The config lives at config/newrelic.yml, and points to a FEDRAMP version of the New Relic service as its host. To access the metrics dashboard, you will need to be connected to VPN.

To get started sending metrics via New Relic APM:

1. Add your New Relic license key to the Rails credentials with key new_relic_key.
2. Optionally, update app_name entries in config/newrelic.yml with what is registered for your application in New Relic
3. Comment out the agent_enabled: false line in config/newrelic.yml
4. Add the Javascript snippet provided by New Relic into application.html.erb. It is recommended to vary this based on environment (i.e. include one snippet for staging and another for production).

Digital Analytics Program (DAP) code has been included for the Production environment, associated with GSA.

If Iv Cbv Payroll is for another agency, update the agency line in app/views/layouts/application.html.erb

See CODEOWNERS.md for some information on repo structure.

Documentation is currently stored in CMS Confluence: https://confluenceent.cms.gov/display/SFIV/Consent-based+Verification+%28CBV%29+for+Payroll

Our ADRs are stored in CMS Confluence: https://confluenceent.cms.gov/pages/viewpage.action?pageId=693666588

See CONTRIBUTING.md.

The CBV team is taking a community-first and open source approach to the product development of this tool. We believe government software should be made in the open and be built and licensed such that anyone can download the code, run it themselves without paying money to third parties or using proprietary software, and use it as they will.

We know that we can learn from a wide variety of communities, including those who will use or will be impacted by the tool, who are experts in technology, or who have experience with similar technologies deployed in other spaces. We are dedicated to creating forums for continuous conversation and feedback to help shape the design and development of the tool.

We also recognize capacity building as a key part of involving a diverse open source community. We are doing our best to use accessible language, provide technical and process documents, and offer support to community members with a wide variety of backgrounds and skillsets.

See COMMUNITY_GUIDELINES.md.

See GOVERNANCE.md

If you have ideas for how we can improve or add to our capacity building efforts and methods for welcoming people into our community, please let us know by sending an email to: ffs at nava pbc dot com. If you would like to comment on the tool itself, please let us know by filing an issue on our GitHub repository.

We adhere to the CMS Open Source Policy. If you have any questions, just shoot us an email.

Submit a vulnerability: Unfortunately, we cannot accept secure submissions via email or via GitHub Issues. Please use our website to submit vulnerabilities at https://hhs.responsibledisclosure.com. HHS maintains an acknowledgements page to recognize your efforts on behalf of the American public, but you are also welcome to submit anonymously.

For more information about our Security, Vulnerability, and Responsible Disclosure Policies, see SECURITY.md.

This project is in the public domain within the United States, and copyright and related rights in the work worldwide are waived through the CC0 1.0 Universal public domain dedication as indicated in LICENSE.

All contributions to this project will be released under the CC0 dedication. By submitting a pull request or issue, you are agreeing to comply with this waiver of copyright interest.

See CODEOWNERS.md