docs update for jwt + move code of conduct

docs/_data/navigation.yml

@@ -32,6 +32,8 @@ docs:
     children:
       - title: "Configuration"
         url: /docs/running/configuration/
+      - title: "Secrets"
+        url: /docs/running/secrets/
       - title: "Database Migrations"
         url: /docs/running/migrations/
   - title: "Architecture"
@@ -62,5 +64,7 @@ docs:
         url: /docs/development/tools/
       - title: "Contributor's Guide"
         url: /docs/development/contributing/
+      - title: "Code of Conduct"
+        url: /docs/development/code-of-conduct/
       - title: "REST API"
         url: /docs/development/rest/

docs/_docs/02-01-configuration.md

@@ -3,7 +3,10 @@ title: Configuration
 permalink: /docs/running/configuration/
 ---
 
+{% include toc %}
+
 ## Overview
+{:.no_toc}
 
 Talk, like many web applications, requires manual configuration via environment
 variables to configure the server for your specific needs. This is following the
@@ -49,19 +52,11 @@ see how the configuration is parsed.
 
 ### JWT
 
-If a non-HMAC based signing method is used (such as `RS256` or `ES256`) as your
-choice for `TALK_JWT_ALG`, you must use a PEM encoded certificate.
-If you are using the core auth method, then a private key must be provided as we
-then perform key signing.
-If you are using an external mechanism to handle key signing by passing the auth
-details through the PYM bridge (documentation on the way!) then you can instead
-provide a public key.
+The following are configuration shared with every type of secret used.
 
 - `TALK_JWT_ALG` (_optional_) - the algorithm used to sign/verify JWT's used for
   session management. Read up about alternative algorithms on the
   [jsonwebtoken](https://www.npmjs.com/package/jsonwebtoken#algorithms-supported) package. (Default `HS256`)
-- `TALK_JWT_SECRET` (*required*) - The shared secret or certificate (depending
-  on your choice of `TALK_JWT_ALG`) used for jwt tokens.
 - `TALK_JWT_EXPIRY` (_optional_) - the expiry duration (`exp`) for the tokens
   issued for logged in sessions. (Default `1 day`)
 - `TALK_JWT_ISSUER` (_optional_) - the issuer (`iss`) claim for login JWT
@@ -69,6 +64,10 @@ provide a public key.
 - `TALK_JWT_AUDIENCE` (_optional_) - the audience (`aud`) claim for login JWT
   tokens. (Default `talk`)
 
+**You must also specify secrets as either the `TALK_JWT_SECRET` or the `TALK_JWT_SECRETS`
+variable. Refer to the [Secrets Documentation]({{ "/docs/running/secrets/" | absolute_url }})
+on the contents of those variables.**
+
 ### Email
 
 - `TALK_SMTP_EMAIL` (*required for email*) - the address to send emails from

docs/_docs/02-02-secrets.md

@@ -0,0 +1,106 @@
+---
+title: Secrets
+permalink: /docs/running/secrets/
+---
+
+{% include toc %}
+
+## Secret Types
+
+We support two types of secrets.
+
+- Shared secrets
+- Asymmetric Secrets
+
+### Shared Secret
+
+You would use a shared secret when you have no need to share the tokens with
+other applications in your organization.
+
+Supported signing algorithms:
+
+- HS256
+- HS384
+- HS512
+
+These must be provided in the form:
+
+```json
+{
+  "secret": "<my secret key>"
+}
+```
+
+### Asymmetric Secret
+
+You would use a asymmetric secret when you want to share the token in your
+organization, and would like to pass an existing auth token to Talk in order to
+authenticate your users. (Documentation on how to do this is pending!).
+
+Supported signing algorithms:
+
+- RS256
+- RS384
+- RS512
+- ES256
+- ES384
+- ES512
+
+These must be provided in the form:
+
+```json
+{
+  "public": "<the PEM encoded public key>",
+  "private": "<the PEM encoded private key>"
+}
+```
+
+Note that when using the asymmetric keys as discussed above, the certificates
+must have their newlines replaced with `\\n`, this is to ensure that the
+newlines are preserved after JSON decoding. Not doing so will result in parsing
+errors.
+
+## Authentication Types
+
+Talk also supports two methods of providing authenticationd details.
+
+- Single key: this is used when your secrets do not need to be rotated.
+- Multiple keys: this is used when you expect to rotate your secrets.
+
+### Single Key
+
+When using a single key, you can utilize the following configuration style:
+
+- `TALK_JWT_SECRET` (*required*) - The shared secret or certificate (depending
+  on your choice of `TALK_JWT_ALG`) used for jwt tokens.
+
+An example of this:
+
+```bash
+# for a shared secret
+TALK_JWT_SECRET={"secret": "<my secret string>"}
+
+# for a asymmetric secret
+TALK_JWT_SECRET={"private": "<my private key>", "public": "<my public key>"}
+```
+
+### Multiple Key
+
+When using a multiple keys, you can utilize the following configuration style:
+
+- `TALK_JWT_SECRETS` (_optional_) - used when specifying multiple secrets used
+  for key rotations. This is a JSON encoded array, where each element matches
+  the JWT Secret pattern.
+
+All secrets also get a `kid` field which uniquely identifies a given key and
+will sign all tokens with that `kid` for later identification.
+
+An example of this:
+
+```bash
+# for a shared secret
+TALK_JWT_SECRETS=[{"kid" "1", "secret": "<my secret string>"}, {"kid" "2", "secret": "<my other secret string>"}]
+
+# for a asymmetric secret
+TALK_JWT_SECRETS=[{"kid": "1", "private": "<my private key>", "public": "<my public key>"}, {"kid": "2", "private": "<my other private key>", "public": "<my other public key>"}]
+```

docs/_docs/05-03-code-of-conduct.md

@@ -1,4 +1,7 @@
-# Contributor Covenant Code of Conduct
+---
+title: Contributor Covenant Code of Conduct
+permalink: /docs/development/code-of-conduct/
+---
 
 ## Our Pledge
 
@@ -9,8 +12,7 @@ We commit to enforce and evolve this code over the duration of the project.
 
 ## Expected behavior
 
-
-* Be supportive of each other. 
+* Be supportive of each other.
 * Be collaborative. Involve others in brainstorms, sketching sessions, code reviews, planning documents, and the like. It’s not only okay to ask for help or feedback often, it’s unacceptable not to do so.
 * Be generous and kind in both giving and accepting critique. Critique is a natural and important part of our culture. Good critiques are kind, respectful, clear, and constructive, focused on goals and requirements rather than personal preferences. You are expected to give and receive criticism with grace.
 * Be humane. Be polite and friendly in all forms of communication, especially remote communication, where opportunities for misunderstanding are greater. Use sarcasm carefully. Tone is hard to decipher online; make judicious use of emoji to aid in communication.
@@ -19,8 +21,8 @@ We commit to enforce and evolve this code over the duration of the project.
 * Respect people’s boundaries.
 * Do not make it personal.
 * Use welcoming and inclusive language.
-* Offer to help if you see someone struggling or otherwise in need of assistance (taking care not to be patronizing or disrespectful). 
-* If someone approaches you looking for help, be generous with your time; if you’re under a deadline, direct them to someone else who may be of assistance. 
+* Offer to help if you see someone struggling or otherwise in need of assistance (taking care not to be patronizing or disrespectful).
+* If someone approaches you looking for help, be generous with your time; if you’re under a deadline, direct them to someone else who may be of assistance.
 * Go out of your way to include people in jokes or memes, recognizing that we want to build an environment free of cliques.
 * Show empathy towards other community members
 
@@ -34,6 +36,7 @@ Harassment includes, but is not limited to: deliberate intimidation; stalking; u
 Furthermore, any behavior or language which is unwelcoming—whether or not it rises to the level of harassment—is also strongly discouraged. Much exclusionary behavior takes the form of microaggressions—subtle put-downs which may be unconsciously delivered. Regardless of intent, microaggressions can have a significant negative impact on victims and have no place on our team.
 
 Other inappropriate behavior:
+
 *	Threats
 *	Slurs
 *	Pornography
@@ -43,7 +46,7 @@ Other inappropriate behavior:
 *	Impersonation of someone else
 *	Violating someone’s privacy
 
-If you feel that someone has harassed you or otherwise treated you or someone else inappropriately, please alert the project lead at andrewl@mozillafoundation.org.
+If you feel that someone has harassed you or otherwise treated you or someone else inappropriately, please alert the project lead at [andrewl@mozillafoundation.org](mailto:andrewl@mozillafoundation.org).
 
 
 ## Our Responsibilities
@@ -61,13 +64,14 @@ This Code of Conduct applies both within project spaces and in public spaces whe
 These guidelines are ambitious, and we’re not always going to succeed in meeting them. When something goes wrong—whether it’s a microaggression or an instance of harassment — there are a number of things you can do to address the situation. Depending on your comfort level and the severity of the situation, here are some suggestions:
 
 * Address it directly. If you’re comfortable bringing up the incident with the person who instigated it, pull them aside to discuss how it affected you. Be sure to approach these conversations in a forgiving spirit: an angry or tense conversation will not do either of you any good. If you’re unsure how to go about that, try discussing with your manager or with the people and culture team first—they might have some advice about how to make this conversation happen.
+
 If you’re too frustrated to have a direct conversation, there are a number of alternate routes you can take.
 
 * Talk to a peer or mentor. Your colleagues are likely to have personal and professional experience on which to draw that could be of use to you. If you have someone you’re comfortable approaching, reach out and discuss the situation with them. They may be able to advise on how they would handle it, or direct you to someone who can. The flip side of this, of course, is that you should also be available when your colleagues reach out to you.
 
-* Contact the project lead, Andrew Losowsky, andrewl@mozillafoundation.org, or the technical lead. We will work with you to help you figure out how to ensure that any conflict doesn’t interfere with your work, in confidence if you would prefer.
+* Contact the project lead, Andrew Losowsky, [andrewl@mozillafoundation.org](mailto:andrewl@mozillafoundation.org), or the technical lead. We will work with you to help you figure out how to ensure that any conflict doesn’t interfere with your work, in confidence if you would prefer.
 
-* Talk to Chris Lawrence. Chris oversees the project. He can be contacted at clawrence@mozillafoundation.org.
+* Talk to Chris Lawrence. Chris oversees the project. He can be contacted at [clawrence@mozillafoundation.org](mailto:clawrence@mozillafoundation.org).
 
 If you feel you have been unfairly accused of violating this code of conduct, you should contact Chris with a concise description of your grievance.