chore: fix docs, build, doctor

documentation/dsls/DSL:-AshAuthentication.Strategy.OAuth2.md

@@ -3,7 +3,13 @@ This file was generated by Spark. Do not edit it by hand.
 -->
 # DSL: AshAuthentication.Strategy.OAuth2
 
-Strategy for authenticating using an OAuth 2.0 server as the source of truth.
+Strategy for authenticating using any OAuth 2.0 server as the source of truth.
+
+This authentication strategy provides registration and sign-in for users using a
+remote [OAuth 2.0](https://oauth.net/2/) server as the source of truth. You
+will be required to provide either a "register" or a "sign-in" action depending
+on your configuration, which the strategy will attempt to validate for common
+misconfigurations.
 
 This strategy wraps the excellent [`assent`](https://hex.pm/packages/assent)
 package, which provides OAuth 2.0 capabilities.

documentation/dsls/DSL:-AshAuthentication.UserIdentity.md

@@ -5,12 +5,18 @@ This file was generated by Spark. Do not edit it by hand.
 
 An Ash extension which generates the default user identities resource.
 
+If you plan to support multiple different strategies at once (eg giving your
+users the choice of more than one authentication provider, or signing them into
+multiple services simultaneously) then you will want to create a resource with
+this extension enabled. It is used to keep track of the links between your
+local user records and their many remote identities.
+
 The user identities resource is used to store information returned by remote
 authentication strategies (such as those provided by OAuth2) and maps them to
 your user resource(s).  This provides the following benefits:
 
   1. A user can be signed in to multiple authentication strategies at once.
-  2. For those provides which support it AshAuthentication can handle
+  2. For those providers that support it, AshAuthentication can handle
      automatic refreshing of tokens.
 
 ## Storage

documentation/tutorials/get-started.md

@@ -197,7 +197,7 @@ end
 - [Github](/documentation/tutorials/github.md)
 - [Google](/documentation/tutorials/google.md)
 - [Magic Links](/documentation/tutorials/magic-links.md)
-- [Auth0](/documentation/tutorials/auth-0.md)
+- [Auth0](/documentation/tutorials/auth0.md)
 - Open ID: `AshAuthentication.Strategy.Oidc`
 - OAuth2: `AshAuthentication.Strategy.OAuth2`
 

lib/ash_authentication/igniter.ex

@@ -1,6 +1,8 @@
 defmodule AshAuthentication.Igniter do
   @moduledoc "Codemods for working with AshAuthentication"
 
+  @doc "Adds a secret to a secret module that reads from application env"
+  @spec add_secret_from_env(Igniter.t(), module(), Ash.Resource.t(), list(atom), atom()) :: Igniter.t()
   def add_secret_from_env(igniter, module, resource, path, env_key) do
     otp_app = Igniter.Project.Application.app_name()
 

lib/mix/tasks/ash_authentication.install.ex

@@ -1,12 +1,20 @@
 defmodule Mix.Tasks.AshAuthentication.Install do
+  @moduledoc """
+  The igniter installer for AshAuthentication.
+  """
+
+  @shortdoc "Installs AshAuthentication. Invoke with `mix igniter.install ash_authentication`"
+
   use Igniter.Mix.Task
 
+  @impl Igniter.Mix.Task
   def info(_argv, _parent) do
     %Igniter.Mix.Task.Info{
       adds_deps: [{:bcrypt_elixir, "~> 3.0"}]
     }
   end
 
+  @impl Igniter.Mix.Task
   def igniter(igniter, argv) do
     accounts_domain = Igniter.Code.Module.module_name("Accounts")
     token_resource = Igniter.Code.Module.module_name("Accounts.Token")
@@ -25,10 +33,25 @@ defmodule Mix.Tasks.AshAuthentication.Install do
     |> generate_token_resource(token_resource, argv, resource_args)
     |> Igniter.Project.Application.add_new_child({AshAuthentication.Supervisor, otp_app: otp_app})
     |> setup_data_layer(repo)
-    |> generate_user_resource(user_resource, argv, resource_args, token_resource, secrets_module, otp_app)
+    |> generate_user_resource(
+      user_resource,
+      argv,
+      resource_args,
+      token_resource,
+      secrets_module,
+      otp_app
+    )
   end
 
-  defp generate_user_resource(igniter, user_resource, argv, resource_args, token_resource, secrets_module, otp_app) do
+  defp generate_user_resource(
+         igniter,
+         user_resource,
+         argv,
+         resource_args,
+         token_resource,
+         secrets_module,
+         otp_app
+       ) do
     case Igniter.Code.Module.find_module(igniter, user_resource) do
       {:ok, {igniter, _, _}} ->
         {:ok,
@@ -47,11 +70,18 @@ defmodule Mix.Tasks.AshAuthentication.Install do
             extensions
           end
 
-        dev_secret = :crypto.strong_rand_bytes(32) |> Base.encode64(padding: false) |> binary_part(0, 32)
-        test_secret = :crypto.strong_rand_bytes(32) |> Base.encode64(padding: false) |> binary_part(0, 32)
-        runtime_secret = {:code, quote do
-          System.get_env("TOKEN_SIGNING_SECRET") || raise "Missing environment variable `TOKEN_SIGNING_SECRET`!"
-        end}
+        dev_secret =
+          :crypto.strong_rand_bytes(32) |> Base.encode64(padding: false) |> binary_part(0, 32)
+
+        test_secret =
+          :crypto.strong_rand_bytes(32) |> Base.encode64(padding: false) |> binary_part(0, 32)
+
+        runtime_secret =
+          {:code,
+           quote do
+             System.get_env("TOKEN_SIGNING_SECRET") ||
+               raise "Missing environment variable `TOKEN_SIGNING_SECRET`!"
+           end}
 
         igniter
         |> Igniter.compose_task(
@@ -63,13 +93,45 @@ defmodule Mix.Tasks.AshAuthentication.Install do
           ] ++ argv ++ resource_args
         )
         |> Spark.Igniter.set_option(user_resource, [:authentication, :tokens, :enabled?], true)
-        |> Spark.Igniter.set_option(user_resource, [:authentication, :tokens, :token_resource], token_resource)
-        |> Spark.Igniter.set_option(user_resource, [:authentication, :tokens, :token_resource], token_resource)
-        |> Spark.Igniter.set_option(user_resource, [:authentication, :tokens, :signing_secret], :token_signing_secret)
-        |> Igniter.Project.Config.configure_new("dev.exs", otp_app, [:token_signing_secret], dev_secret)
-        |> Igniter.Project.Config.configure_new("test.exs", otp_app, [:token_signing_secret], test_secret)
-        |> Igniter.Project.Config.configure_runtime_env(igniter, otp_app, [:token_signing_secret], runtime_secret)
-        |> AshAuthentication.Igniter.add_secret_from_env(secrets_module, user_resource, [:authentication, :tokens, :signing_secret], :token_signing_secret)
+        |> Spark.Igniter.set_option(
+          user_resource,
+          [:authentication, :tokens, :token_resource],
+          token_resource
+        )
+        |> Spark.Igniter.set_option(
+          user_resource,
+          [:authentication, :tokens, :token_resource],
+          token_resource
+        )
+        |> Spark.Igniter.set_option(
+          user_resource,
+          [:authentication, :tokens, :signing_secret],
+          :token_signing_secret
+        )
+        |> Igniter.Project.Config.configure_new(
+          "dev.exs",
+          otp_app,
+          [:token_signing_secret],
+          dev_secret
+        )
+        |> Igniter.Project.Config.configure_new(
+          "test.exs",
+          otp_app,
+          [:token_signing_secret],
+          test_secret
+        )
+        |> Igniter.Project.Config.configure_runtime_env(
+          igniter,
+          otp_app,
+          [:token_signing_secret],
+          runtime_secret
+        )
+        |> AshAuthentication.Igniter.add_secret_from_env(
+          secrets_module,
+          user_resource,
+          [:authentication, :tokens, :signing_secret],
+          :token_signing_secret
+        )
     end
   end
 

mix.exs

@@ -68,6 +68,7 @@ defmodule AshAuthentication.MixProject do
       extras: [
         {"README.md", name: "Home"},
         "documentation/tutorials/get-started.md",
+        "documentation/tutorials/password.md",
         "documentation/tutorials/auth0.md",
         "documentation/tutorials/github.md",
         "documentation/tutorials/google.md",

mix.lock

@@ -69,7 +69,6 @@
   "splode": {:hex, :splode, "0.2.4", "71046334c39605095ca4bed5d008372e56454060997da14f9868534c17b84b53", [:mix], [], "hexpm", "ca3b95f0d8d4b482b5357954fec857abd0fa3ea509d623334c1328e7382044c2"},
   "stream_data": {:hex, :stream_data, "1.1.1", "fd515ca95619cca83ba08b20f5e814aaf1e5ebff114659dc9731f966c9226246", [:mix], [], "hexpm", "45d0cd46bd06738463fd53f22b70042dbb58c384bb99ef4e7576e7bb7d3b8c8c"},
   "telemetry": {:hex, :telemetry, "1.3.0", "fedebbae410d715cf8e7062c96a1ef32ec22e764197f70cda73d82778d61e7a2", [:rebar3], [], "hexpm", "7015fc8919dbe63764f4b4b87a95b7c0996bd539e0d499be6ec9d7f3875b79e6"},
-  "ucwidth": {:hex, :ucwidth, "0.2.0", "1f0a440f541d895dff142275b96355f7e91e15bca525d4a0cc788ea51f0e3441", [:mix], [], "hexpm", "c1efd1798b8eeb11fb2bec3cafa3dd9c0c3647bee020543f0340b996177355bf"},
   "xema": {:hex, :xema, "0.17.4", "e958baaf1f8238414c0646a6946a2fa8812673d14771aefc12af182b97d20665", [:mix], [{:conv_case, "~> 0.2.2", [hex: :conv_case, repo: "hexpm", optional: false]}, {:decimal, "~> 1.0 or ~> 2.0", [hex: :decimal, repo: "hexpm", optional: true]}], "hexpm", "faf638de7c424326f089475db8077c86506af971537eb2097e06124c5e0e4240"},
   "yamerl": {:hex, :yamerl, "0.10.0", "4ff81fee2f1f6a46f1700c0d880b24d193ddb74bd14ef42cb0bcf46e81ef2f8e", [:rebar3], [], "hexpm", "346adb2963f1051dc837a2364e4acf6eb7d80097c0f53cbdc3046ec8ec4b4e6e"},
   "yaml_elixir": {:hex, :yaml_elixir, "2.11.0", "9e9ccd134e861c66b84825a3542a1c22ba33f338d82c07282f4f1f52d847bd50", [:mix], [{:yamerl, "~> 0.10", [hex: :yamerl, repo: "hexpm", optional: false]}], "hexpm", "53cc28357ee7eb952344995787f4bb8cc3cecbf189652236e9b163e8ce1bc242"},