Add GraphQL API for managing rooms

guides/api.md

@@ -0,0 +1,39 @@
+# Hubs Server API
+Reticulum includes a [GraphQL](https://graphql.org/) API to better allow you to write plugins or customize the app to your needs. 
+
+## Accessing the API
+The API can be accessed by sending `GET` or `POST` requests to `/api/v2_alpha/` with a valid GraphQL document in the request body. Note: This path is subject to change as we get out of early testing.
+
+Requests can be sent by a variety of standard tools:
+- an `HTTP` client library, 
+- a command line tool like `curl`, 
+- a GraphQL-specific client library, 
+- any other tool that speaks `HTTP`. 
+
+Reticulum ships with [GraphiQL](https://github.com/graphql/graphiql/tree/main/packages/graphiql#graphiql), a graphical interactive in-browser GraphQL IDE that makes it easy to test and learn the API. It can be accessed by navigating to `<your_hubs_cloud_endpoint>/api/v2_alpha/graphiql`. [This example workspace](../test/api/v2/graphiql-workspace-2020-10-28-15-28-39.json) demonstrates several queries and can be loaded into the GraphiQL interface. You will have to generate and supply your own API access tokens.
+
+## Authentication and Authorization
+Most requests require an API Access Token for authentication and authorization. 
+
+### API Access Token Types
+There are two types of API Access Tokens: 
+- `:account` tokens act on behalf of a specific user
+- `:app` tokens act on behalf of the hubs cloud itself
+
+### Scopes
+When generating API Access Tokens, you specify which `scopes` to grant that token. Scopes allow the token to be used to perform specific actions.
+
+| Scope | API Actions |
+| --:            |         --- |      
+| `read_rooms` | `myRooms`, `favoriteRooms`, `publicRooms` |
+| `write_rooms` | `createRoom`, `updateRoom` |
+
+Scopes, actions, and token types are expected to expand over time.
+
+Tokens can be generated on the command line with `mix generate_api_token`. Soon this method will be replaced with a web API and interface.
+
+### Using API Access Tokens
+
+To attach an API Access Token to a request, add the `HTTP` header `Authorization` with value `Bearer: <your API token>`. 
+
+

lib/mix/tasks/generate_api_token.ex

@@ -0,0 +1,78 @@
+defmodule Mix.Tasks.GenerateApiToken do
+  @moduledoc "Generates an Api Token for the given account email"
+
+  use Mix.Task
+
+  alias Ret.{Account}
+  alias Ret.Api.TokenUtils
+
+  @impl Mix.Task
+  def run(_) do
+    user_or_app =
+      "Generate user token or app token? [user or app]"
+      |> Mix.shell().prompt()
+      |> String.trim()
+
+    case user_or_app do
+      "user" ->
+        gen_user_token()
+
+      "app" ->
+        gen_app_token()
+
+      _ ->
+        Mix.shell().error("Input not recognized. Type \"user\" or \"app\".")
+        run([])
+    end
+  end
+
+  defp gen_user_token() do
+    email =
+      "Enter email address of the user whose account will be associated in this token: [foo@bar.com]\n"
+      |> Mix.shell().prompt()
+      |> String.trim()
+
+    Mix.Task.run("app.start")
+
+    case Account.account_for_email(email) do
+      nil ->
+        Mix.shell().error("Could not find account for the given email address: #{email}")
+
+      account ->
+        IO.puts("Account found:")
+
+        account
+        |> Inspect.Algebra.to_doc(%Inspect.Opts{})
+        |> Inspect.Algebra.format(80)
+        |> IO.puts()
+
+        if Mix.shell().yes?("Generate token for this account [#{email}]?") do
+          gen_token_for_account(account)
+        end
+    end
+  end
+
+  defp gen_app_token() do
+    if Mix.shell().yes?("Are you sure you want to generate an app token?") do
+      Mix.Task.run("app.start")
+
+      case TokenUtils.gen_app_token() do
+        {:ok, token, _claims} ->
+          Mix.shell().info("Successfully generated token:\n#{token}")
+
+        {:error, reason} ->
+          Mix.shell().error("Error: #{reason}")
+      end
+    end
+  end
+
+  defp gen_token_for_account(account) do
+    case TokenUtils.gen_token_for_account(account) do
+      {:ok, token, _claims} ->
+        Mix.shell().info("Successfully generated token:\n#{token}")
+
+      {:error, reason} ->
+        Mix.shell().error("Error: #{reason}")
+    end
+  end
+end

lib/ret/account.ex

@@ -24,6 +24,14 @@ defmodule Ret.Account do
     timestamps()
   end
 
+  def query do
+    from(account in Account)
+  end
+
+  def where_account_id_is(query, id) do
+    from(account in query, where: account.account_id == ^id)
+  end
+
   def has_accounts?(), do: from(a in Account, limit: 1) |> Repo.exists?()
   def has_admin_accounts?(), do: from(a in Account, limit: 1) |> where(is_admin: true) |> Repo.exists?()
   def exists_for_email?(email), do: account_for_email(email) != nil

lib/ret/api/can_credentials.ex

@@ -0,0 +1,103 @@
+defimpl Canada.Can, for: Ret.Api.Credentials do
+  import Canada, only: [can?: 2]
+  alias Ret.{Account, Hub}
+  alias Ret.Api.{Credentials, Scopes}
+
+  def can?(
+        %Credentials{is_revoked: true},
+        _action,
+        _resource
+      ) do
+    false
+  end
+
+  def can?(
+        %Credentials{subject_type: :app, scopes: scopes},
+        :get_rooms_created_by,
+        %Account{} = account
+      ) do
+    Scopes.read_rooms() in scopes and can?(:reticulum_app_token, get_rooms_created_by(account))
+  end
+
+  def can?(
+        %Credentials{subject_type: :account, account: subject, scopes: scopes},
+        :get_rooms_created_by,
+        %Account{} = account
+      ) do
+    Scopes.read_rooms() in scopes and can?(subject, get_rooms_created_by(account))
+  end
+
+  def can?(
+        %Credentials{subject_type: :app, scopes: scopes},
+        :get_favorite_rooms_of,
+        %Account{} = account
+      ) do
+    Scopes.read_rooms() in scopes and can?(:reticulum_app_token, get_favorite_rooms_of(account))
+  end
+
+  def can?(
+        %Credentials{subject_type: :account, account: subject, scopes: scopes},
+        :get_favorite_rooms_of,
+        %Account{} = account
+      ) do
+    Scopes.read_rooms() in scopes and can?(subject, get_favorite_rooms_of(account))
+  end
+
+  def can?(
+        %Credentials{subject_type: :app, scopes: scopes},
+        :get_public_rooms,
+        _
+      ) do
+    Scopes.read_rooms() in scopes and can?(:reticulum_app_token, get_public_rooms(nil))
+  end
+
+  def can?(
+        %Credentials{subject_type: :account, account: subject, scopes: scopes},
+        :get_public_rooms,
+        _
+      ) do
+    Scopes.read_rooms() in scopes and can?(subject, get_public_rooms(nil))
+  end
+
+  def can?(
+        %Credentials{subject_type: :app, scopes: scopes},
+        :create_room,
+        _
+      ) do
+    Scopes.write_rooms() in scopes && can?(:reticulum_app_token, create_hub(nil))
+  end
+
+  def can?(
+        %Credentials{subject_type: :account, account: subject, scopes: scopes},
+        :create_room,
+        _
+      ) do
+    Scopes.write_rooms() in scopes && can?(subject, create_hub(nil))
+  end
+
+  def can?(%Credentials{subject_type: :app, scopes: scopes}, :embed_hub, %Hub{} = hub) do
+    Scopes.read_rooms() in scopes && can?(:reticulum_app_token, embed_hub(hub))
+  end
+
+  def can?(%Credentials{subject_type: :account, account: subject, scopes: scopes}, :embed_hub, %Hub{} = hub) do
+    Scopes.read_rooms() in scopes && can?(subject, embed_hub(hub))
+  end
+
+  def can?(
+        %Credentials{subject_type: :app, scopes: scopes},
+        :update_room,
+        %Hub{} = hub
+      ) do
+    Scopes.write_rooms() in scopes && can?(:reticulum_app_token, update_hub(hub))
+  end
+
+  def can?(
+        %Credentials{subject_type: :account, account: subject, scopes: scopes},
+        :update_room,
+        %Hub{} = hub
+      ) do
+    Scopes.write_rooms() in scopes && can?(subject, update_hub(hub))
+  end
+
+  def can?(_, _, _), do: false
+end

lib/ret/api/credentials.ex

@@ -0,0 +1,128 @@
+defmodule Ret.Api.Credentials do
+  @moduledoc """
+  Credentials for API access.
+  """
+  alias Ret.Api.Credentials
+
+  alias Ret.Account
+
+  use Ecto.Schema
+  import Ecto.Query, only: [from: 2]
+  import Ecto.Changeset
+  alias Ret.Api.{TokenSubjectType, ScopeType}
+
+  @schema_prefix "ret0"
+  @primary_key {:api_credentials_id, :id, autogenerate: true}
+
+  schema "api_credentials" do
+    field(:api_credentials_sid, :string)
+    field(:token_hash, :string)
+    field(:subject_type, TokenSubjectType)
+    field(:is_revoked, :boolean)
+    field(:scopes, {:array, ScopeType})
+
+    belongs_to(:account, Account, references: :account_id)
+    timestamps()
+  end
+
+  @required_keys [:api_credentials_sid, :token_hash, :subject_type, :is_revoked, :scopes]
+  @permitted_keys @required_keys
+
+  def generate_credentials(%{subject_type: _st, scopes: _sc, account_or_nil: account_or_nil} = params) do
+    sid = Ret.Sids.generate_sid()
+
+    # Use 18 bytes (not 16, the default) to avoid having all tokens end in "09"
+    # See https://github.com/patricksrobertson/secure_random.ex/issues/11
+    # Prefix the sid to the rest of the token for ease of management
+    token = "#{sid}.#{SecureRandom.urlsafe_base64(18)}"
+
+    params =
+      Map.merge(params, %{
+        api_credentials_sid: sid,
+        token_hash: Ret.Crypto.hash(token),
+        is_revoked: false
+      })
+
+    case %Credentials{}
+         |> change()
+         |> cast(params, @permitted_keys)
+         |> maybe_put_assoc_account(account_or_nil)
+         |> validate_required(@required_keys)
+         |> validate_change(:subject_type, &validate_field/2)
+         |> validate_change(:scopes, &validate_field/2)
+         |> unique_constraint(:api_credentials_sid)
+         |> unique_constraint(:token_hash)
+         # TODO: We can pass multiple fields to unique_contraint when we update ecto
+         # https://github.com/elixir-ecto/ecto/pull/3276
+         |> Ret.Repo.insert() do
+      {:ok, credentials} ->
+        {:ok, token, credentials}
+
+      {:error, reason} ->
+        {:error, reason}
+    end
+  end
+
+  defp maybe_put_assoc_account(changeset, %Account{} = account) do
+    put_assoc(changeset, :account, account)
+  end
+
+  defp maybe_put_assoc_account(changeset, nil) do
+    changeset
+  end
+
+  defp validate_single_scope_type(scope) do
+    if ScopeType.valid_value?(scope) do
+      []
+    else
+      [invalid_scope: "Unrecognized scope type. Got #{scope}."]
+    end
+  end
+
+  def validate_field(:scopes, scopes) do
+    Enum.reduce(scopes, [], fn scope, errors ->
+      errors ++ validate_single_scope_type(scope)
+    end)
+  end
+
+  def validate_field(:subject_type, subject_type) do
+    if TokenSubjectType.valid_value?(subject_type) do
+      []
+    else
+      [invalid_subject_type: "Unrecognized subject type. Must be app or account. Got #{subject_type}."]
+    end
+  end
+
+  def revoke(credentials) do
+    credentials
+    |> change()
+    |> put_change(:is_revoked, true)
+    |> Ret.Repo.update()
+  end
+
+  def query do
+    from(c in Credentials, left_join: a in Account, on: c.account_id == a.account_id, preload: [account: a])
+  end
+
+  def where_sid_is(query, sid) do
+    from([credential, _account] in query,
+      where: credential.api_credentials_sid == ^sid
+    )
+  end
+
+  def where_token_hash_is(query, hash) do
+    from([credential, _account] in query,
+      where: credential.token_hash == ^hash
+    )
+  end
+
+  def where_account_is(query, %Account{account_id: id}) do
+    from([credential, _account] in query,
+      where: credential.account_id == ^id
+    )
+  end
+
+  def app_token_query() do
+    from(c in Credentials, where: c.subject_type == ^:app)
+  end
+end

lib/ret/api/dataloader.ex

@@ -0,0 +1,11 @@
+defmodule Ret.Api.Dataloader do
+  @moduledoc "Configuration for dataloader"
+
+  import Ecto.Query
+  alias Ret.{Repo, Scene, SceneListing}
+
+  def source(), do: Dataloader.Ecto.new(Repo, query: &query/2)
+  # Guard against loading removed scenes or delisted scene listings
+  def query(Scene, _), do: from(s in Scene, where: s.state != ^:removed)
+  def query(SceneListing, _), do: from(sl in SceneListing, where: sl.state != ^:delisted)
+end