Elixir: Plug Header Groups & Plug Name

[halostatue]

• Elixir: Plug Header Groups & Plug Name (d307900)

  • Add support for header groups in AppIdentity.Plug to better handle fallback headers. Kinetic’s original Elixir implementation always verified only the first value from a list of headers, like so:

     with [] <- Conn.get_req_header(conn, "header-1"),
          [] <- Conn.get_req_header(conn, "header-2"),
          [] <- Conn.get_req_header(conn, "header-3") do
      :error
    else
      [value | _] -> {:ok, value}
    end

    AppIdentity.Plug always processes all values of a header and puts the result in a map with the header name as the key, it meant that we would have had to check these results in turn. Instead, the header_groups option allows you to collect all related headers into one result key:

    plug AppIdentity.Plug, header_groups: %{
     "app" => ["header-1", "header-2", "header-3"]
    }, ...

  • Add support for alternate names so that AppIdentity.Plug can be specified multiple times in a pipeline and will store its data separately.

• Spec: Extend security details for secret handling (8b7edd0)

  These changes do not affect any implementation, but adds some security recommendations for secret handling that were omitted from the initial released version of the specification.

  1. Generated secret values should be prefixed for improved leak detection by scanning tools, such as those deployed by GitHub.

     The reference implementations do not generate application objects except for the integrated test suites, and the secrets are always generated on each independent run.

  2. Secret values should be stored in memory-safe and leak-resistant mechanisms.

     The reference implementations already use closures to wrap the secret and custom inspection definitions to ensure that the secrets cannot be accidentally leaked.

[mikestok]

I would like to print out and review the docs as a separate task so that we can release this now.

I'm at a nitpicking phase where my main nits seems to be:

• front loading sentences
• simplifying sentences
  • removing subclauses by rewriting
  • removing much of the emphasis so that it doesn't become less important to the reader
  • for example "Should no proof headers be included, the request is considered invalid" ; "If there are no proof headers the request is invalid"
• moving important stuff earlier

For technical writing I have to ditch the writing style I like and think more along the guidelines in https://www.plainlanguage.gov/guidelines/

[halostatue]

I would like to print out and review the docs as a separate task so that we can release this now.

I’m going to be busy with internal tasks today and we’re not yet ready to pull this into our projects because of other changes blocking this test release. Just remember to flag the release date to be changed from today when putting other comments in place so that we get that updated. I’d rather have the documentation fixed than not.

If you see particularly egregious text that needs fixing, please also check the Typescript and Ruby to see if the text is equally awful. We probably won’t fix it in this PR (I think that I’ve seen an issue we need to resolve in the Ruby code, but haven’t verified it to be sure), but I would like to have it flagged.