cmd/pomerium : refactor main to more testable (#112)

- cmd/pomerium: refactor global timeouts to be configurable
- cmd/pomerium: add tests
- cmd/pomerium: remove debug flag, set with env vars only
- cmd/pomerium: global ping now returns version not OK
- proxy: validate shared secret encoding and length
- docs: add timeout to example policy
- docs: document timeouts and cors
- docs: update pomerium logo
- docs: add policy authorization docs

docs/.vuepress/public/logo-no-text.svg

@@ -0,0 +1 @@
+<svg id="Layer_1" data-name="Layer 1" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 597.47 295"><defs><style>.cls-1{fill:#fff;}.cls-2{fill:#443266;}</style></defs><title>logo-no-text</title><path class="cls-1" d="M365.41,490.89v-.09h0S365.41,490.86,365.41,490.89Z" transform="translate(-90.42 -202)"/><path class="cls-1" d="M365.4,490.8v.09s0-.06,0-.09Z" transform="translate(-90.42 -202)"/><path class="cls-1" d="M365.41,490.89v-.09h0S365.41,490.86,365.41,490.89Z" transform="translate(-90.42 -202)"/><path class="cls-1" d="M365.4,490.8v.09s0-.06,0-.09Z" transform="translate(-90.42 -202)"/><path class="cls-2" d="M90.42,497c0-162.92,133.75-295,298.73-295S687.89,334.08,687.89,497" transform="translate(-90.42 -202)"/><path class="cls-1" d="M599.29,335.48a39.21,39.21,0,0,0-39.2-39.21H218.22A39.21,39.21,0,0,0,179,335.48V497h27.09V451.87h0c0-30.64,24.6-55.47,54.89-55.47s54.84,24.83,54.88,55.47h0V497h19.6V451.87h0c0-30.64,24.59-55.47,54.88-55.47s54.85,24.83,54.89,55.47h0V497h19.6V451.87h0c0-30.64,24.6-55.47,54.89-55.47s54.84,24.83,54.88,55.47h0V497h24.66ZM206.11,376.21c0-30.67,24.57-55.54,54.89-55.54s54.88,24.87,54.88,55.54Zm129.37,0c0-30.67,24.58-55.54,54.89-55.54s54.89,24.87,54.89,55.54Zm129.38,0c0-30.67,24.57-55.54,54.89-55.54s54.88,24.87,54.88,55.54Z" transform="translate(-90.42 -202)"/><path class="cls-1" d="M365.4,490.8v.09s0-.06,0-.09Z" transform="translate(-90.42 -202)"/><path class="cls-1" d="M365.41,490.89v-.09h0S365.41,490.86,365.41,490.89Z" transform="translate(-90.42 -202)"/></svg>

docs/readme.md

@@ -1,8 +1,8 @@
 ---
 home: true
 heroImage: logo.svg
-heroText: Pomerium
-tagline: Identity-aware access proxy.
+heroText:  " "
+tagline: Pomerium is a context and identity aware access proxy. 
 actionText: Read the docs
 actionLink: /docs/
 ---

docs/reference/readme.md

@@ -61,10 +61,75 @@ head -c32 /dev/urandom | base64
 - Filetype: `json` or `yaml`
 - Required
 
-Policy contains the routes, and their access policies. For example,
+Policy contains route specific settings, and access control details. For example,
 
 <<< @/policy.example.yaml
 
+A list of policy configuration variables follows.
+
+#### From
+
+- `yaml`/`json` setting: `from`
+- Type: `string` domain
+- Required
+- Example: `httpbin.corp.example.com`
+
+`From` is externally accessible source of the proxied request.
+
+#### To
+
+- `yaml`/`json` setting: `to`
+- Type: `string` domain
+- Required
+- Example: `httpbin` , `192.1.20.12:20`, `http://neverssl.com`
+
+`To` is the destination of a proxied request. It can be an internal resource, or an external resource.
+
+#### Allowed Users
+
+- `yaml`/`json` setting: `allowed_users`
+- Type: collection of `strings`
+- Required
+- Example: `alice@pomerium.io` , `bob@contractor.co`
+
+Allowed users is a collection of whitelisted users to authorize for a given route.
+
+#### Allowed Groups
+
+- `yaml`/`json` setting: `allowed_groups`
+- Type: collection of `strings`
+- Required
+- Example: `admins` , `support@company.com`
+
+Allowed groups is a collection of whitelisted groups to authorize for a given route.
+
+#### Allowed Domains
+
+- `yaml`/`json` setting: `allowed_domains`
+- Type: collection of `strings`
+- Required
+- Example: `pomerium.io` , `gmail.com`
+
+Allowed domains is a collection of whitelisted domains to authorize for a given route.
+
+#### CORS Preflight
+
+- `yaml`/`json` setting: `cors_allow_preflight`
+- Type: `bool`
+- Optional
+- Default: `false`
+
+Allow unauthenticated HTTP OPTIONS requests as [per the CORS spec](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#Preflighted_requests).
+
+### Timeout
+
+- `yaml`/`json` setting: `timeout`
+- Type: [Go Duration](https://golang.org/pkg/time/#Duration.String) `string`
+- Optional
+- Default: `30s`
+
+Policy timeout establishes the per-route timeout value. Cannot exceed global timeout values.
+
 ### Debug
 
 - Environmental Variable: `POMERIUM_DEBUG`
@@ -116,6 +181,19 @@ Certificate is the x509 _public-key_ used to establish secure HTTP and gRPC conn
 
 Certificate key is the x509 _private-key_ used to establish secure HTTP and gRPC connections. If unset, pomerium will attempt to find and use `./privkey.pem`.
 
+### Timeouts
+
+- Environmental Variables: `TIMEOUT_READ` `TIMEOUT_WRITE` `TIMEOUT_READ_HEADER` `TIMEOUT_IDLE`
+- Type: [Go Duration](https://golang.org/pkg/time/#Duration.String) `string`
+- Example: `TIMEOUT_READ=30s`
+- Defaults: `TIMEOUT_READ_HEADER=10s` `TIMEOUT_READ=30s` `TIMEOUT_WRITE=0` `TIMEOUT_IDLE=5m`
+
+Timeouts set the global server timeouts. For route-specific timeouts, see `Policy`.
+
+![cloudflare blog on timeouts](https://blog.cloudflare.com/content/images/2016/06/Timeouts-001.png)
+
+> For a deep dive on timeout values see [these](https://blog.cloudflare.com/the-complete-guide-to-golang-net-http-timeouts/) [two](https://blog.cloudflare.com/exposing-go-on-the-internet/) excellent blog posts.
+
 ## Authenticate Service
 
 ### Authenticate Service URL
@@ -241,8 +319,16 @@ Certificate Authority is set when behind-the-ingress service communication uses
 - Type: map of `strings` key value pairs
 - Example: `X-Content-Type-Options:nosniff,X-Frame-Options:SAMEORIGIN`
 - To disable: `disable:true`
+- Default :
 
-Headers specifies a mapping of [HTTP Header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers) to be added to proxied requests. *Nota bene* Downstream application headers will be overwritten by Pomerium's headers on conflict. 
+  ```javascript
+  X-Content-Type-Options : nosniff,
+  X-Frame-Options:SAMEORIGIN,
+  X-XSS-Protection:1; mode=block,
+  Strict-Transport-Security:max-age=31536000; includeSubDomains; preload,
+  ```
+
+  Headers specifies a mapping of [HTTP Header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers) to be added to proxied requests. _Nota bene_ Downstream application headers will be overwritten by Pomerium's headers on conflict.
 
 By default, conservative [secure HTTP headers](https://www.owasp.org/index.php/OWASP_Secure_Headers_Project) are set.