update docs for 1.3.0 release

Author: aztechian

NARRATIVE.md

@@ -2,7 +2,7 @@
 
 ## Context
 
-For many industries, there is a necessity to develop or deploy software systems on disconnected – or air-gapped – infrastructure. Banking, Energy, Government and Aviation are examples of industries that need such protection.  
+For many industries, there is a necessity to develop or deploy software systems on disconnected, or "air-gapped" infrastructure. This pattern is observed in Public Sector, Banking, Energy, SCADA, Defense, Justice Department, Telecommunications, Aviation and Payment Processing industries where such protection is desired.
 
 The need usually comes from protecting data that resides on the air-gapped system, and thus the protection of the system itself is necessary. However, software and software development are constantly changing – so much so that keeping static air-gapped systems is a higher risk than the reward of newer software. We know then, custom and COTS software must be eventually updated and the recent rise of Agile and DevOps pushes those update cycles to an ever-faster iteration time.
 
@@ -37,7 +37,7 @@ Because Bridgr is to be a trusted tool in bringing data to potentially sensitive
 - WIP: Prefixing a PR title with `WIP` causes the PR to not be mergeable until the developer removes WIP. This is a useful GitLab feature that I miss in stock GitHub.
 - Dependabot: This service daily checks the code repository for libraries that the application uses for vulnerabilities and creates a new issue and PR to address and fix the vulnerability. In the case of Bridgr, it reads the `go.mod` file to identify libraries being used but can support other languages to varying degrees of integration (on a JavaScript project I have, it can even make a PR with the fixed library version in package.json - all I have to do is click “Merge”).
 - Codecov: This is a code coverage analysis tool, using the results from unit tests. Badges are available to put in the README so that users/developers can see right off what level of quality code to expect. Additional integration comes from evaluating PRs on each commit, and disallowing merging if there is a drop or regression in the overall coverage OR in the code modified by the PR.
-- CodeScene: This is a tool that has been developed from the book [*Your code as a crime scene*](https://pragprog.com/book/atcrime/code-as-a-crime-scene). It uses metadata from the git repository to identify and prioritize hidden risks, suggest improvements and make early warnings of delivery risk before issues manifest. It is predictive behavioral analysis of how an application is being developed using temporal history rather than static code analysis (which is a snapshot in time). This is a unique and otherwise paid service that is free for FOSS projects. This provides product owner guidance for where to utilize resources most effectively and for developers to have situational awareness - such as where (in the code) to prioritize code reviews. See <https://empear.com/docs/CodeSceneUseCasesAndRoles.pdf> for much more detail.
+- CodeScene: This is a tool that has been developed from the book [_Your code as a crime scene_](https://pragprog.com/book/atcrime/code-as-a-crime-scene). It uses metadata from the git repository to identify and prioritize hidden risks, suggest improvements and make early warnings of delivery risk before issues manifest. It is predictive behavioral analysis of how an application is being developed using temporal history rather than static code analysis (which is a snapshot in time). This is a unique and otherwise paid service that is free for FOSS projects. This provides product owner guidance for where to utilize resources most effectively and for developers to have situational awareness - such as where (in the code) to prioritize code reviews. See <https://empear.com/docs/CodeSceneUseCasesAndRoles.pdf> for much more detail.
 
 The above project management and tooling is intended create as much transparency, developer accessibility and trust as possible for a tool that relies on these traits for acceptance.
 

README.md

@@ -42,26 +42,62 @@ By default, Bridgr will create a `packages` directory with all artifacts gathere
 
 Also by default, Bridgr will look for a `bridge.yml` manifest file in the directory where it is being run. This can be overridden with the `-c` option to bridgr to specify a configuration file elsewhere.
 
-``` shell
+```shell
 ./bridgr -c path/to/another/bridge.yml
 ```
 
 To only run one of the repository types, simply give that type after any configuration options. As an example, to only run the Files type, execute Bridgr like this:
 
-``` shell
+```shell
 ./bridgr -v files
 ```
 
 Additional command line options include:
 
-| Option           | Meaning                                                                                                                                             |
-| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
-| -v  /  --verbose | Verbose Output                                                                                                                                      |
-| -n  /  --dry-run | Dry-run. Only do setup, don't fetch artifacts                                                                                                       |
-| -c  /  --config  | Specify an alternate configuration file                                                                                                             |
-| --version        | Print the version of Bridgr and exit. The output of stderr can be redirected to /dev/null to get just the version string.                           |
-| -H  /  --host    | Run Bridgr in "hosting" mode. This mode does no downloading of artifacts, but makes Bridgr into a simple HTTP server. See `Hosting` for more detail |
-| -l  /  --listen  | The listen address for Bridgr in hosting mode. This is only effective when coupled with the `-H` flag. Default is `:8080`                           |
+| Option         | Meaning                                                                                                                                             |
+| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| -v / --verbose | Verbose Output                                                                                                                                      |
+| -n / --dry-run | Dry-run. Only do setup, don't fetch artifacts                                                                                                       |
+| -c / --config  | Specify an alternate configuration file                                                                                                             |
+| --version      | Print the version of Bridgr and exit. The output of stderr can be redirected to /dev/null to get just the version string.                           |
+| -H / --host    | Run Bridgr in "hosting" mode. This mode does no downloading of artifacts, but makes Bridgr into a simple HTTP server. See `Hosting` for more detail |
+| -l / --listen  | The listen address for Bridgr in hosting mode. This is only effective when coupled with the `-H` flag. Default is `:8080`                           |
+
+### Artifacts requiring authentication
+
+Bridgr support getting authenticated artifacts for `Files`, `Docker` and `Git`. Sensitive credential information is passed to Bridgr with environment variables. It does not support putting credentials in the configuration file because it risks users comitting these credentials into version control. Bridgr intends to promote good credential hygene.
+
+Providing credentials follows a pattern of environment variable naming
+
+- Username -> `BRIDGR_[HOST]_USER`
+- Password -> `BRIDGR_[HOST]_PASS`
+- API Token -> `BRIDGR_[HOST]_TOKEN`
+
+Only one of Password or Token can be given. If both are provided, token will override.
+
+The `[HOST]` portion of the environment variable above should be the hostname of the URL being fetched, converted to uppercase and `.` replaced with `_`. This is most easily shown with examples.
+
+Fetching authentication protected docker hub image:
+
+```shell
+BRIDGR_DOCKER_IO_USER=user BRIDGR_DOCKER_IO_PASS=secret bridgr docker
+```
+
+In this case we have provided a username (user) and password (secret) for the default docker registry (docker.io). When the docker worker is run, and any images are specified from docker.io, bridgr will look for these two variables for credential information.
+
+Another example for files:
+
+```shell
+BRIDGR_PROTECTED_MYSERVER_COM_USER=user BRIDGR_PROTECTED_MYSERVER_COM_PASS=secret bridgr files
+```
+
+And, finally for git - but this time showing a token (typical with Github and Gitlab):
+
+```shell
+BRIDGR_GITHUB_COM_TOKEN=abcdefg123456789 bridgr git
+```
+
+In this case, we don't need to specify the `_USER` part of the credential, because the git worker assumes a username of `git`, and Github or Gitlab just need it to _not_ be blank. The worker does this for you.
 
 ## Hosting mode
 
@@ -104,18 +140,21 @@ Using new (as of go 1.11) [modules-style](https://github.com/golang/go/wiki/Modu
 Project structure following [these guidelines](https://github.com/golang-standards/project-layout)
 Example project showing [CI pipeline](https://gitlab.com/pantomath-io/demo-tools)
 
-We will use the following libraries to do heavy lifting:
+Significant Go modules used by `Bridgr`:
 
 - go-git
 - docker.io/go-docker
-- yaml.v2
+- yaml.v3
 - vfsgen
 
 Potential for schema definition/validation of the YAML config file: [https://github.com/rjbs/rx](https://github.com/rjbs/rx)
 Potential library for creating iso9660 (ISO) files [https://github.com/kdomanski/iso9660](https://github.com/kdomanski/iso9660)
 
 ## Release History
 
+- 1.3.0
+  - Add authentication support
+  - Update to Go version 1.13
 - 1.2.1
   - Fixes for usability bugs
 - 1.2.0
@@ -134,19 +173,20 @@ Potential library for creating iso9660 (ISO) files [https://github.com/kdomanski
 
 Ian Martin – [email protected]
 
-Distributed under the MIT license. See ``LICENSE`` for more information.
+Distributed under the MIT license. See `LICENSE` for more information.
 
 [https://github.com/aztechian/bridgr](https://github.com/aztechian/)
 
 ## Contributing
 
-1. Fork it (<https://github.com/aztechian/bridgr/fork>)
+1. [Fork it](https://github.com/aztechian/bridgr/fork)
 2. Create your feature branch (`git checkout -b feature/fooBar`)
 3. Commit your changes (`git commit -am 'Add some fooBar'`)
-4. Push to the branch (`git push -u origin feature/fooBar`)
+4. Push to the branch (`git push -u origin HEAD`)
 5. Create a new Pull Request
 
 <!-- Markdown link & img dfn's -->
+
 [gh-downloads]: https://img.shields.io/github/downloads/aztechian/bridgr/total.svg
 [gh-dl-url]: releases/
 [license]: https://img.shields.io/github/license/aztechian/bridgr