COOP-270: Add top level docs

.check.exs

@@ -0,0 +1,7 @@
+[
+  tools: [
+    {:compiler, env: %{"MIX_ENV" => "test"}},
+    {:formatter, env: %{"MIX_ENV" => "test"}},
+    {:ex_doc, env: %{"MIX_ENV" => "test"}}
+  ]
+]

.github/workflows/ci.yaml

@@ -74,25 +74,12 @@ jobs:
       - name: Deps get
         run: mix deps.get
 
-      - name: Dependencies Check
-        run: mix deps.unlock --check-unused
-
-      # Experimental: compile without warnings (throw it away if macro magic creates problems)
+        # Experimental: compile without warnings (throw it away if macro magic creates problems)
       - name: Compiles without warnings
         run: mix compile --warnings-as-errors
 
-      # Check Format
-      - name: Check Formatting
-        run: mix format --check-formatted
-
-      - name: Credo
-        run: mix credo -a --strict
-
-      - name: Test
-        run: mix test
-
-      - name: Dialyzer
-        run: mix dialyzer
+      - name: Mix Check
+        run: mix check        
 
   alls-green:
     if: always()

lib/cloudflare_access_ex.ex

@@ -1,18 +1,90 @@
 defmodule CloudflareAccessEx do
   @moduledoc """
-  Documentation for `CloudflareAccessEx`.
-  """
+    This library aims to simplify the process of sitting an application behind Cloudflare Access.
+
+    By default, this library starts an Application (see `CloudflareAccessEx.Application`).
+    The application will read Application config to determine which Cloudflare Access domains to
+    retrieve JWKs from. These keys can then be used to verify the application tokens sent by Cloudflare Access
+    when your application is accessed.
+
+    The [Cloudflare docs](https://developers.cloudflare.com/cloudflare-one/identity/authorization-cookie/application-token/)
+    provide more information.
+
+    TODO:
+    The library also provides a Plug (see `CloudflareAccessEx.Plug`) that can be used to to extract and
+    verify tokens from requests.
+
+    Usage:
+
+    1. Add `cloudflare_access_ex` to your list of dependencies in `mix.exs`. Note that the
+       `:runtime` option can be used to disable Jwks polling in selected environments (i.e. `:test` and `:dev`)
+
+           def deps do
+             [
+               {:cloudflare_access_ex, "~> 0.1.0", runtime: Mix.env() not in [:test, :dev]}
+             ]
+           end
+
+       If you wish to startup the application manually, you can opt out of the runtime dependency and start the
+       supervisor manually:
+
+           def deps do
+             [
+               {:cloudflare_access_ex, "~> 0.1.0", runtime: false}
+             ]
+           end
+
+       in your application module:
+
+           CloudflareAccessEx.Supervisor.start_link(... TODO ...)
+
+    2. Get the audience tag from the Cloudflare Access dashboard for your application.
+       [Instruction here](https://developers.cloudflare.com/cloudflare-one/identity/authorization-cookie/validating-json/#get-your-aud-tag).
+
+    3. Configure the application:
+
+           config :cloudflare_access_ex, :my_cfa_app,
+               domain: "example.cloudflareaccess.com"
+               # this is the audience tag retrieved on step 2
+               audience: "a8d3b7..."
+
+       Multiple applications can be configured by adding more keys to the `:cloudflare_access_ex` config. i.e.
+
+           config :cloudflare_access_ex, :my_cfa_app,
+               domain: "example.cloudflareaccess.com"
+               audience: "a8d3b7..."
+
+           config :cloudflare_access_ex, :my_other_cfa_app,
+               domain: "example.cloudflareaccess.com"
+               audience: "7309b8..."
+
+       There will only be one process that fetches Jwks keys for each domain. It's also possible to consolidate the
+       duplicate configuration for the domain string like so:
+
+           config :cloudflare_access_ex, example,
+               domain: "example.cloudflareaccess.com"
+
+           config :cloudflare_access_ex, :my_cfa_app,
+               domain: :example, audience: "a8d3b7..."
+
+           config :cloudflare_access_ex, :my_other_cfa_app,
+               domain: :example, audience: "7309b8..."
+
+    4. Verify tokens either using `CloudflareAccessEx.Plug` (this will return 401 for invalid tokens by default):
+
+           plug CloudflareAccessEx.Plug,
+             application: :my_cfa_app
 
-  @doc """
-  Hello world.
+       or using `CloudflareAccessEx.AccessTokenVerifier` directly if you need even more control:
 
-  ## Examples
+           alias CloudflareAccessEx.AccessTokenVerifier
 
-      iex> CloudflareAccessEx.hello()
-      :world
+           verifier = AccessTokenVerifier.create(:my_cfa_app)
+           {:ok, token} = conn |> AccessTokenVerifier.verify(verifier)
 
+           case token do
+             :anonymous -> # do something
+             {:user, %{id: _, email: _}} -> # do something else
+           end
   """
-  def hello do
-    :world
-  end
 end

mix.exs

@@ -7,7 +7,15 @@ defmodule CloudflareAccessEx.MixProject do
       version: "0.1.0",
       elixir: "~> 1.14",
       start_permanent: Mix.env() == :prod,
-      deps: deps()
+      deps: deps(),
+      preferred_cli_env: [
+        check: :test,
+        credo: :test,
+        dialyzer: :test,
+        doctor: :test,
+        sobelow: :test,
+        "deps.audit": :test
+      ]
     ]
   end
 
@@ -22,8 +30,11 @@ defmodule CloudflareAccessEx.MixProject do
   # Run "mix help deps" to learn about dependencies.
   defp deps do
     [
-      {:credo, "~> 1.7", only: [:dev, :test], runtime: false},
-      {:dialyxir, "~> 1.3", only: [:dev, :test], runtime: false}
+      {:credo, "~> 1.7", only: :test, runtime: false},
+      {:dialyxir, "~> 1.3", only: :test, runtime: false},
+      {:doctor, "~> 0.21.0", only: :test, runtime: false},
+      {:ex_check, "~> 0.14.0", only: :test, runtime: false},
+      {:ex_doc, "~> 0.27", only: :test, runtime: false}
     ]
   end
 end

mix.lock

@@ -1,8 +1,17 @@
 %{
   "bunt": {:hex, :bunt, "0.2.1", "e2d4792f7bc0ced7583ab54922808919518d0e57ee162901a16a1b6664ef3b14", [:mix], [], "hexpm", "a330bfb4245239787b15005e66ae6845c9cd524a288f0d141c148b02603777a5"},
   "credo": {:hex, :credo, "1.7.0", "6119bee47272e85995598ee04f2ebbed3e947678dee048d10b5feca139435f75", [:mix], [{:bunt, "~> 0.2.1", [hex: :bunt, repo: "hexpm", optional: false]}, {:file_system, "~> 0.2.8", [hex: :file_system, repo: "hexpm", optional: false]}, {:jason, "~> 1.0", [hex: :jason, repo: "hexpm", optional: false]}], "hexpm", "6839fcf63d1f0d1c0f450abc8564a57c43d644077ab96f2934563e68b8a769d7"},
+  "decimal": {:hex, :decimal, "2.1.1", "5611dca5d4b2c3dd497dec8f68751f1f1a54755e8ed2a966c2633cf885973ad6", [:mix], [], "hexpm", "53cfe5f497ed0e7771ae1a475575603d77425099ba5faef9394932b35020ffcc"},
   "dialyxir": {:hex, :dialyxir, "1.4.1", "a22ed1e7bd3a3e3f197b68d806ef66acb61ee8f57b3ac85fc5d57354c5482a93", [:mix], [{:erlex, ">= 0.2.6", [hex: :erlex, repo: "hexpm", optional: false]}], "hexpm", "84b795d6d7796297cca5a3118444b80c7d94f7ce247d49886e7c291e1ae49801"},
+  "doctor": {:hex, :doctor, "0.21.0", "20ef89355c67778e206225fe74913e96141c4d001cb04efdeba1a2a9704f1ab5", [:mix], [{:decimal, "~> 2.0", [hex: :decimal, repo: "hexpm", optional: false]}], "hexpm", "a227831daa79784eb24cdeedfa403c46a4cb7d0eab0e31232ec654314447e4e0"},
+  "earmark_parser": {:hex, :earmark_parser, "1.4.36", "487ea8ef9bdc659f085e6e654f3c3feea1d36ac3943edf9d2ef6c98de9174c13", [:mix], [], "hexpm", "a524e395634bdcf60a616efe77fd79561bec2e930d8b82745df06ab4e844400a"},
   "erlex": {:hex, :erlex, "0.2.6", "c7987d15e899c7a2f34f5420d2a2ea0d659682c06ac607572df55a43753aa12e", [:mix], [], "hexpm", "2ed2e25711feb44d52b17d2780eabf998452f6efda104877a3881c2f8c0c0c75"},
+  "ex_check": {:hex, :ex_check, "0.14.0", "d6fbe0bcc51cf38fea276f5bc2af0c9ae0a2bb059f602f8de88709421dae4f0e", [:mix], [], "hexpm", "8a602e98c66e6a4be3a639321f1f545292042f290f91fa942a285888c6868af0"},
+  "ex_doc": {:hex, :ex_doc, "0.30.6", "5f8b54854b240a2b55c9734c4b1d0dd7bdd41f71a095d42a70445c03cf05a281", [:mix], [{:earmark_parser, "~> 1.4.31", [hex: :earmark_parser, repo: "hexpm", optional: false]}, {:makeup_elixir, "~> 0.14", [hex: :makeup_elixir, repo: "hexpm", optional: false]}, {:makeup_erlang, "~> 0.1", [hex: :makeup_erlang, repo: "hexpm", optional: false]}], "hexpm", "bd48f2ddacf4e482c727f9293d9498e0881597eae6ddc3d9562bd7923375109f"},
   "file_system": {:hex, :file_system, "0.2.10", "fb082005a9cd1711c05b5248710f8826b02d7d1784e7c3451f9c1231d4fc162d", [:mix], [], "hexpm", "41195edbfb562a593726eda3b3e8b103a309b733ad25f3d642ba49696bf715dc"},
   "jason": {:hex, :jason, "1.4.1", "af1504e35f629ddcdd6addb3513c3853991f694921b1b9368b0bd32beb9f1b63", [:mix], [{:decimal, "~> 1.0 or ~> 2.0", [hex: :decimal, repo: "hexpm", optional: true]}], "hexpm", "fbb01ecdfd565b56261302f7e1fcc27c4fb8f32d56eab74db621fc154604a7a1"},
+  "makeup": {:hex, :makeup, "1.1.0", "6b67c8bc2882a6b6a445859952a602afc1a41c2e08379ca057c0f525366fc3ca", [:mix], [{:nimble_parsec, "~> 1.2.2 or ~> 1.3", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "0a45ed501f4a8897f580eabf99a2e5234ea3e75a4373c8a52824f6e873be57a6"},
+  "makeup_elixir": {:hex, :makeup_elixir, "0.16.1", "cc9e3ca312f1cfeccc572b37a09980287e243648108384b97ff2b76e505c3555", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}, {:nimble_parsec, "~> 1.2.3 or ~> 1.3", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "e127a341ad1b209bd80f7bd1620a15693a9908ed780c3b763bccf7d200c767c6"},
+  "makeup_erlang": {:hex, :makeup_erlang, "0.1.2", "ad87296a092a46e03b7e9b0be7631ddcf64c790fa68a9ef5323b6cbb36affc72", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}], "hexpm", "f3f5a1ca93ce6e092d92b6d9c049bcda58a3b617a8d888f8e7231c85630e8108"},
+  "nimble_parsec": {:hex, :nimble_parsec, "1.3.1", "2c54013ecf170e249e9291ed0a62e5832f70a476c61da16f6aac6dca0189f2af", [:mix], [], "hexpm", "2682e3c0b2eb58d90c6375fc0cc30bc7be06f365bf72608804fb9cffa5e1b167"},
 }

test/cloudflare_access_ex_test.exs

@@ -1,8 +1,4 @@
 defmodule CloudflareAccessExTest do
   use ExUnit.Case
   doctest CloudflareAccessEx
-
-  test "greets the world" do
-    assert CloudflareAccessEx.hello() == :world
-  end
 end