Improve hawk.gen.resource

Author: Raphexion

README.md

@@ -72,9 +72,13 @@ mix hawk.gen.resource MyApp.Courses MyApp.Course \
 
 This creates the facade, policy, reader, JSON:API adapter, LiveView adapter, and
 writer skeleton. Pass `--read-only` to generate `writer: false` and omit the
-writer. The generator is intentionally conservative: it gives you the standard
-Hawk shape, then you tighten policy, filters, labels, docs, and writer rules by
-hand.
+writer. Pass `--web MyAppWeb` to also generate a Phoenix JSON:API controller,
+clickable LiveView index/show modules and templates, and a router snippet file
+beside the generated web files. The generated LiveViews use
+`Hawk.Authority.Session.authority_or_public/1`, so they work for public demos and
+can later pick up a session-backed authority. The generator is intentionally
+conservative: it gives you the standard Hawk shape, then you tighten policy,
+filters, labels, docs, and writer rules by hand.
 
 ### JSON:API adapter
 
@@ -301,7 +305,12 @@ end
 `public` is anonymous readonly access. It is not system access and still goes
 through the resource policy. Policies expose their read declarations for
 contract validation, so `ResourceContract` can catch scoped policy filters that
-are not declared by the reader.
+are not declared by the reader. For simple ownership-based writes, pass
+`owned_by:` to require model/changeset fields to match authority scopes:
+
+```elixir
+write(roles: [:teacher], owned_by: [teacher_id: :teacher_id])
+```
 
 Policy matrix tests can use `Hawk.Policy.Assertions` to keep role coverage
 compact:
@@ -381,6 +390,25 @@ defmodule MyApp.Courses.Writer do
 end
 ```
 
+### Authority conventions
+
+Hawk does not authenticate users itself. Apps can use the small session/assign
+convention helpers to carry an already-resolved authority through controllers and
+LiveViews:
+
+```elixir
+authority = MyAppWeb.Auth.authority_for(conn)
+conn = Hawk.Authority.Plug.call(conn, resolver: fn _conn -> authority end)
+
+session_authority = Hawk.Authority.Session.dump(authority)
+authority = Hawk.Authority.Session.authority_or_public(session)
+```
+
+`Hawk.Authority.Plug` assigns `:hawk_authority` on the conn, while
+`Hawk.LiveView.AuthorityHook` can assign the same key from a dumped session value
+with LiveView `on_mount`. Missing authority falls back to readonly public access,
+not system access.
+
 `Hawk.Writer.Resource` generates `change_create/2` / `create/2` and
 `change_update/3` / `update/3` from the same pipelines. `change_*` functions
 return non-persisting changesets with `action: :validate`, which is the boundary
@@ -721,8 +749,10 @@ end
 ```
 
 The contract test checks that JSON:API attributes, relationships,
-creatable/updatable fields, reader preloads, sorts, and filters agree with the
-model and reader declarations.
+creatable/updatable fields, reader preloads, sorts, filters, and scoped policy
+filters agree with the model, reader, and policy declarations. For resources
+where every exposed relationship is expected to be include/preloadable, call
+`Hawk.ResourceContract.validate!/3` with `require_relationship_preloads: true`.
 
 ### JSON:API controller contract test
 

docs/hawk-resource-direction.md

@@ -77,7 +77,7 @@ policy_filter AND caller_filter AND resource_forced_filter
 
 Policy is the security boundary. Adapter filters from JSON:API, LiveView params, or internal callers are additional narrowing only. Unknown filters fail closed. Preloads use the related resource's own Reader and Policy.
 
-Policy declarations are introspectable so resource contracts can validate the seam between Policy and Reader: every scoped policy filter key must be declared as a reader filter or custom filter handler. Role matrices should be tested with Hawk's policy assertion helpers rather than repeated hand-written `read_filter/1` assertions.
+Policy declarations are introspectable so resource contracts can validate the seam between Policy and Reader: every scoped policy filter key must be declared as a reader filter or custom filter handler. Role matrices should be tested with Hawk's policy assertion helpers rather than repeated hand-written `read_filter/1` assertions. Apps can use the session/assign authority convention helpers for Plug and LiveView handoff, but authentication remains application-owned.
 
 There are no hidden read bypasses. Even system reads should use `Authority.system()` and flow through the same machinery.
 
@@ -87,7 +87,7 @@ There are no hidden read bypasses. Even system reads should use `Authority.syste
 
 System writes should also validate policy explicitly; `system` can be allowed, but it should not bypass the policy-validation path.
 
-JSON:API relationship reads can expose projections over internal database shape, including `many_to_many` associations where the join schema is not itself part of the external API. JSON:API relationship writes are intentionally limited to `belongs_to` associations because those map cleanly to writer attrs through the owning foreign key. `has_many`, `has_one`, and `many_to_many` mutations need explicit writer/action workflows instead of being implied from JSON:API relationship linkage. Plain CRUD deletion can use the writer DSL's `delete(:default)` helper; ownership-specific or cascading deletes should remain explicit writer/action workflows.
+JSON:API relationship reads can expose projections over internal database shape, including `many_to_many` associations where the join schema is not itself part of the external API. JSON:API relationship writes are intentionally limited to `belongs_to` associations because those map cleanly to writer attrs through the owning foreign key. `has_many`, `has_one`, and `many_to_many` mutations need explicit writer/action workflows instead of being implied from JSON:API relationship linkage. Plain CRUD deletion can use the writer DSL's `delete(:default)` helper. Simple owner-scoped writers can use `write(..., owned_by: [field: :scope])`; cascading deletes and multi-resource ownership rules should remain explicit writer/action workflows.
 
 Actions are resource-scoped workflows/commands. They may orchestrate across resources, use `Ecto.Multi`, send emails, enqueue jobs, and perform broader side effects. They remain declared, authorized, documented, telemetry-instrumented, and testable.
 
@@ -157,6 +157,6 @@ Telemetry should avoid raw IDs, request params, mutation attrs, and sensitive pa
 
 ## Route and capability consistency
 
-Hawk should eventually provide explicit Phoenix route macros that generate only supported routes. Hand-written routes remain possible, but contract tests should catch route/capability drift.
+Hawk's resource generator can produce the first Phoenix layer — JSON:API controller, clickable LiveView index/show files, and a router snippet — while apps still decide where routes belong. Full route macros can come later if repeated apps show the snippets are still too manual. Hand-written routes remain possible, but contract tests should catch route/capability drift.
 
 `use Hawk.JsonApi.Controller` and `use Hawk.LiveView` should eventually need only `resource: MyApp.Courses`, with model and adapter metadata inferred from the resource facade.

lib/hawk/authority/plug.ex

@@ -0,0 +1,30 @@
+defmodule Hawk.Authority.Plug do
+  @moduledoc """
+  Optional Plug-style authority assignment convention.
+
+  Configure with a resolver that turns a conn into `Hawk.Authority`:
+
+      plug Hawk.Authority.Plug, resolver: &MyAppWeb.Auth.authority/1
+
+  If the resolver returns `nil`, Hawk assigns `Hawk.Authority.public()`.
+  The authority is stored in `conn.assigns[:hawk_authority]` by default.
+  """
+
+  alias Hawk.Authority
+  alias Hawk.Authority.Session
+
+  def init(opts), do: opts
+
+  def call(conn, opts) do
+    key = Keyword.get(opts, :assign, Session.default_key())
+    resolver = Keyword.get(opts, :resolver, fn _conn -> nil end)
+
+    authority =
+      case resolver.(conn) do
+        %Authority{} = authority -> authority
+        nil -> Authority.public()
+      end
+
+    Session.assign_authority(conn, authority, key)
+  end
+end

lib/hawk/authority/session.ex

@@ -0,0 +1,110 @@
+defmodule Hawk.Authority.Session do
+  @moduledoc """
+  Small helpers for carrying `Hawk.Authority` through web sessions and assigns.
+
+  Hawk does not own application authentication. Apps resolve their current user
+  however they like, then store the resulting authority with these stable keys so
+  controllers and LiveViews can share the same convention.
+  """
+
+  alias Hawk.Authority
+
+  @default_key :hawk_authority
+
+  @doc """
+  Returns Hawk's default assign/session key for authorities.
+  """
+  def default_key, do: @default_key
+
+  @doc """
+  Converts an authority into a session-safe map.
+  """
+  def dump(%Authority{} = authority) do
+    %{
+      "role" => authority.role,
+      "identity" => authority.identity,
+      "readonly?" => authority.readonly?,
+      "system?" => authority.system?,
+      "public?" => authority.public?,
+      "scopes" => authority.scopes,
+      "meta" => authority.meta
+    }
+  end
+
+  @doc """
+  Rebuilds an authority from `dump/1` output.
+  """
+  def load(%{"role" => role, "identity" => identity} = data) do
+    %Authority{
+      role: normalize_atom(role),
+      identity: identity,
+      readonly?: Map.get(data, "readonly?", false),
+      system?: Map.get(data, "system?", false),
+      public?: Map.get(data, "public?", false),
+      scopes: normalize_atom_keys(Map.get(data, "scopes", %{})),
+      meta: Map.get(data, "meta", %{})
+    }
+  end
+
+  def load(%{role: role, identity: identity} = data) do
+    %Authority{
+      role: normalize_atom(role),
+      identity: identity,
+      readonly?: Map.get(data, :readonly?, false),
+      system?: Map.get(data, :system?, false),
+      public?: Map.get(data, :public?, false),
+      scopes: normalize_atom_keys(Map.get(data, :scopes, %{})),
+      meta: Map.get(data, :meta, %{})
+    }
+  end
+
+  def load(nil), do: nil
+
+  @doc """
+  Stores an authority under the configured assign key on a socket/conn/map.
+  """
+  def assign_authority(socket_or_conn, %Authority{} = authority, key \\ @default_key) do
+    assign_value(socket_or_conn, key, authority)
+  end
+
+  @doc """
+  Fetches an authority from assigns or session-like maps.
+  """
+  def fetch_authority(source, key \\ @default_key) do
+    source
+    |> fetch_value(key)
+    |> case do
+      %Authority{} = authority -> {:ok, authority}
+      nil -> :error
+      dumped -> {:ok, load(dumped)}
+    end
+  end
+
+  @doc """
+  Fetches an authority or returns `Hawk.Authority.public()`.
+  """
+  def authority_or_public(source, key \\ @default_key) do
+    case fetch_authority(source, key) do
+      {:ok, authority} -> authority
+      :error -> Authority.public()
+    end
+  end
+
+  defp assign_value(%{assigns: assigns} = value, key, authority) when is_map(assigns) do
+    put_in(value.assigns, Map.put(assigns, key, authority))
+  end
+
+  defp assign_value(value, key, authority) when is_map(value) do
+    Map.put(value, key, authority)
+  end
+
+  defp fetch_value(%{assigns: assigns}, key) when is_map(assigns), do: Map.get(assigns, key)
+  defp fetch_value(%{} = map, key), do: Map.get(map, key) || Map.get(map, to_string(key))
+
+  defp normalize_atom(value) when is_atom(value), do: value
+  defp normalize_atom(value) when is_binary(value), do: String.to_existing_atom(value)
+
+  defp normalize_atom_keys(map) when is_map(map) do
+    Map.new(map, fn {key, value} -> {normalize_atom(key), value} end)
+  end
+end

lib/hawk/live_view/authority_hook.ex

@@ -0,0 +1,22 @@
+defmodule Hawk.LiveView.AuthorityHook do
+  @moduledoc """
+  Optional LiveView `on_mount` convention for assigning Hawk authorities.
+
+  Use after storing a dumped authority in the session with
+  `Hawk.Authority.Session.dump/1`:
+
+      on_mount {Hawk.LiveView.AuthorityHook, []}
+
+  The hook assigns `:hawk_authority`, falling back to `Hawk.Authority.public()`.
+  """
+
+  alias Hawk.Authority.Session
+
+  def on_mount(opts, _params, session, socket) do
+    key = Keyword.get(opts, :assign, Session.default_key())
+    session_key = Keyword.get(opts, :session_key, key)
+    authority = Session.authority_or_public(session, session_key)
+
+    {:cont, Session.assign_authority(socket, authority, key)}
+  end
+end

lib/hawk/policy.ex

@@ -53,23 +53,50 @@ defmodule Hawk.Policy do
 
   defmacro write(opts) when is_list(opts) do
     roles = Keyword.fetch!(opts, :roles)
+    owned_by = Keyword.get(opts, :owned_by, [])
 
     quote do
-      def create?(%Hawk.MutationContext{} = context), do: write_allowed?(context.authority)
-      def update?(%Hawk.MutationContext{} = context), do: write_allowed?(context.authority)
-      def delete?(%Hawk.MutationContext{} = context), do: write_allowed?(context.authority)
+      def create?(%Hawk.MutationContext{} = context),
+        do: write_allowed?(context, unquote(owned_by))
+
+      def update?(%Hawk.MutationContext{} = context),
+        do: write_allowed?(context, unquote(owned_by))
+
+      def delete?(%Hawk.MutationContext{} = context),
+        do: write_allowed?(context, unquote(owned_by))
+
+      defp write_allowed?(%Hawk.MutationContext{} = context, ownership) do
+        authority = context.authority
 
-      defp write_allowed?(%Hawk.Authority{} = authority) do
         cond do
           Hawk.Authority.system?(authority) -> true
           Hawk.Authority.readonly?(authority) -> false
-          authority.role in unquote(roles) -> true
+          authority.role in unquote(roles) -> Hawk.Policy.owned_by?(context, ownership)
           true -> false
         end
       end
     end
   end
 
+  def owned_by?(_context, []), do: true
+
+  def owned_by?(%Hawk.MutationContext{} = context, ownership) when is_list(ownership) do
+    Enum.all?(ownership, fn {field, scope} ->
+      with {:ok, scope_value} <- Hawk.Authority.fetch_scope(context.authority, scope),
+           {:ok, field_value} <- mutation_field(context, field) do
+        field_value == scope_value
+      else
+        _missing -> false
+      end
+    end)
+  end
+
+  defp mutation_field(%Hawk.MutationContext{} = context, field) when is_atom(field) do
+    value = Ecto.Changeset.get_field(context.changeset, field)
+
+    if is_nil(value), do: Map.fetch(context.model, field), else: {:ok, value}
+  end
+
   defp literal_option!(value, _caller) when is_map(value), do: value
 
   defp literal_option!(quoted, caller) do

lib/hawk/resource_contract.ex

@@ -3,12 +3,13 @@ defmodule Hawk.ResourceContract do
   Validates that a Hawk resource's declarations agree with its Ecto model.
   """
 
-  def validate!(resource, model) when is_atom(resource) and is_atom(model) do
+  def validate!(resource, model, opts \\ []) when is_atom(resource) and is_atom(model) do
     json_api = validate_model!(model, json_api_metadata(resource, model))
     reader = resource_module(resource, :reader, Reader)
     policy = resource_module(resource, :policy, Policy)
 
     validate_reader_preloads!(reader, json_api)
+    maybe_validate_relationship_preloads!(reader, json_api, opts)
     validate_reader_sorts!(reader, model)
     validate_reader_filters!(reader, model)
     validate_policy_filters!(policy, reader)
@@ -115,6 +116,17 @@ defmodule Hawk.ResourceContract do
     |> raise_if_any!("reader preloads must be declared JSON:API relationships")
   end
 
+  defp maybe_validate_relationship_preloads!(reader, json_api, opts) do
+    if Keyword.get(opts, :require_relationship_preloads, false) do
+      preloads = reader |> reader_values(:preload_keys) |> MapSet.new()
+
+      json_api.relationships
+      |> Map.keys()
+      |> Enum.reject(&MapSet.member?(preloads, &1))
+      |> raise_if_any!("JSON:API relationships must be declared reader preloads")
+    end
+  end
+
   defp validate_reader_sorts!(reader, model) do
     schema_fields = model.__schema__(:fields) |> MapSet.new()