can no longer read. It is keyed by the session's own account and refreshed only

over that account's own topic.

Delivery is in-product only. Accounts carry no email address and no outbound

mail adapter is configured, so no channel here leaves the application.

Delivery is in-product first and by email second, and the second channel is

the only one that leaves the application. Four things gate it, and all four are

decided twice — once when the delivery is queued and again when it is sent —

because a sent message is the one notification no later authorization check can

withdraw.

The address is the first gate. An account has no address until somebody types

one here; GitHub OAuth is not asked for `user:email`, so no address arrives that

its owner did not choose to give this deployment. A typed address is inert:

`OpenAgents.Notifications.EmailChannel.verified_address/1` is the only read any

send resolves a recipient through, and it returns `nil` until a code mailed to

that address comes back. The code is held as a SHA-256 digest, compared in

constant time, expires in thirty minutes, and is retired after five wrong

guesses. The check constraint `users_notification_email_state_check` refuses a

verified timestamp on a row that names no address, so the gate holds

independently of this application's code. The verification message is the one

thing sent to an unconfirmed address, and it carries the code and nothing about

the account.

The channel is the second. `email_enabled` defaults off and is backfilled false

for every account that already exists, because turning on a channel that leaves

the application for people who chose the inbox is not a default anybody picked.

The category is the third: only `mention` is carried, so no other category

becomes an email by widening. Repository access is the fourth, re-read through

`Repositories.readable_by/2` at send time.

The queued half is durable rather than immediate, because a send happens after

the transaction commits and can fail on somebody else's server.

`Delivery.enqueue/1` writes one `email.delivery` effect inside the transaction

that writes the record, keyed to the same `(user_id, dedupe_key)` pair the

unique index uses, so a replayed fan-out is one record and one message.

`OpenAgents.Effects` owns attempts, backoff, and the terminal `failed`. A

refusal at send time is recorded as a completion with its reason rather than

retried, because none of these four answers improves by being asked again. The

payload names an account and an event and never an address, so no caller can

put a recipient into the queue.

A message carries what a record carries — the kind, the actor's login, the

repository path, and the issue number — plus a link. Not the issue's title, and

not a body.

Evidence: `OpenAgents.Notifications`, `OpenAgents.Notifications.Mentions`,

`OpenAgents.Notifications.EmailChannel`, `OpenAgents.Notifications.Delivery`,

`OpenAgents.Notifications.Email`, `OpenAgents.Effects.Handlers.EmailDelivery`,

`OpenAgents.Issues.update_issue/3`, `OpenAgentsWeb.NotificationsLive`,

`OpenAgentsWeb.UserAuth.on_mount/4`, `test/openagents/notifications_test.exs`,

and `test/openagents_web/live/notifications_live_test.exs`.

`test/openagents/notifications/email_channel_test.exs`,

`test/openagents/notifications/email_delivery_test.exs`,

`test/openagents/notifications/delivery_test.exs`, and

`test/openagents_web/live/notifications_live_test.exs`.

### FORGEAPI-001 — One error envelope, and a route inventory derived from the router

| WORK-002 | `test/openagents/box_runs_test.exs` |

| PROMISE-001 | `test/openagents/promise_registry_test.exs`, `test/openagents_web/controllers/project_controller_test.exs` |

| PROMISE-002 | `test/openagents/promise_registry_test.exs` |

| NOTIFY-001 | `test/openagents/notifications_test.exs`, `test/openagents_web/live/notifications_live_test.exs` |

| NOTIFY-001 | `test/openagents/notifications_test.exs`, `test/openagents/notifications/email_channel_test.exs`, `test/openagents/notifications/email_delivery_test.exs`, `test/openagents/notifications/delivery_test.exs`, `test/openagents_web/live/notifications_live_test.exs` |

| FORGEAPI-001 | `test/openagents_web/controllers/api_error_contract_test.exs`, `test/openagents_web/controllers/api_extension_controller_test.exs`, `test/openagents_web/api_error_test.exs`, `test/openagents_web/controllers/issue_controller_test.exs` |

| FORGEAPI-002 | `test/openagents_web/api_version_posture_test.exs`, `test/openagents_web/plugs/api_v3_rewrite_test.exs` |

# at the `config/runtime.exs`.

config :openagents, OpenAgents.Mailer, adapter: Swoosh.Adapters.Local

# The notification email channel (#141).

#

# `deliverable` is what the settings surface asks before it offers to take an

# address, and it is set here rather than inferred from the Swoosh adapter,

# because the adapter answers the question wrongly in both directions: the

# local adapter is real delivery in development, where the message lands in the

# mailbox preview at "/dev/mailbox", and it is a black hole in production.

# `config/prod.exs` turns it off, and `config/runtime.exs` turns it back on for

# a deployment that configured a provider.

config :openagents, OpenAgents.Notifications.EmailChannel,

  from: {"OpenAgents", "notifications@openagents.com"},

  deliverable: true

config :openagents, OpenAgents.Notifications.Delivery,

  adapter: OpenAgents.Notifications.Delivery.MailerAdapter

# Product analytics (docs/2026-08-21-posthog-integration-runbook.md). The

# default supervisor stays off; OpenAgents.Application starts PostHog.Supervisor

# only when a project token was configured at boot. Error tracking is a

# Disable Swoosh Local Memory Storage

config :swoosh, local: false

# No mail provider until `config/runtime.exs` finds one in the environment. The

# local adapter is still configured, so a stray send would be swallowed rather

# than raised; saying so here means the settings surface declines to collect an

# address instead of accepting one this deployment cannot mail (#141).

config :openagents, OpenAgents.Notifications.EmailChannel, deliverable: false

# Do not print debug messages in production

config :logger, level: :info

  config :openagents, :changelog_backfill_on_boot, true

end

# The mail provider for the notification email channel (#141). Absent by

# default: a deployment that sets no provider keeps `deliverable: false` from

# `config/prod.exs`, the settings surface declines to collect an address, and

# nothing is queued for a channel that cannot send.

#

# The API key is read here and nowhere else, per RELEASE-002: it enters from the

# environment at boot and is absent from source, the build context, and image

# arguments. All three providers are HTTP APIs served by `Swoosh.ApiClient.Req`,

# so none of them adds a dependency or an SMTP credential.

if config_env() == :prod and optional_text.("OPENAGENTS_MAIL_PROVIDER") != nil do

  mail_from_address = required_text.("OPENAGENTS_MAIL_FROM")

  mail_api_key = required_text.("OPENAGENTS_MAIL_API_KEY")

  mailer_config =

    case required_text.("OPENAGENTS_MAIL_PROVIDER") do

      "resend" ->

        [adapter: Swoosh.Adapters.Resend, api_key: mail_api_key]

      "postmark" ->

        [adapter: Swoosh.Adapters.Postmark, api_key: mail_api_key]

      "mailgun" ->

        [

          adapter: Swoosh.Adapters.Mailgun,

          api_key: mail_api_key,

          domain: required_text.("OPENAGENTS_MAIL_DOMAIN")

        ]

      _invalid ->

        raise "environment variable OPENAGENTS_MAIL_PROVIDER must be resend, postmark, or mailgun"

    end

  config :openagents, OpenAgents.Mailer, mailer_config

  config :openagents, OpenAgents.Notifications.EmailChannel,

    from: {"OpenAgents", mail_from_address},

    deliverable: true

end

if config_env() == :prod and runtime_role == :web do

  runtime_environment =

    case required_text.("OPENAGENTS_ENVIRONMENT") do

**Effect CLI** — the TypeScript CLI (`@openagentsinc/cli`) that calls this

surface via `openagents api`.

### Notifications

**Category** — what an account hears about: `mentions`, `issue_comments`,

`assignments`, `issue_activity`, `label_changes`. Each names what it delivers,

so switching one off has an effect you can predict from its name.

**Channel** — where it hears about it. Two: the in-product inbox, which has no

switch because it is the surface itself, and email, which has `email_enabled`

and defaults off. Say category for what and channel for where; a list that

mixes them lets a rename move an account from one answer to the other.

`OpenAgents.Notifications.Preference` keeps the two apart and `switches/0` is

the union.

**Confirmed address** — an address an account typed into its notification

settings and proved by returning a code mailed to it.

`OpenAgents.Notifications.EmailChannel.verified_address/1` is the only read a

send resolves a recipient through, so an address that is merely recorded

reaches nothing. Say confirmed, not verified, of the address; `verified_at` is

the column and confirming is what a person does.

**Delivery** — one queued outbound message,

`OpenAgents.Notifications.Delivery`, carried as an `email.delivery` effect in

the durable outbox. It is not the notification record, which is written in the

transaction and needs no queue, and it is not the message, which is

`OpenAgents.Notifications.Email`.

### Pull requests and stacks

**Pull request** — a repository-scoped proposal to merge one hosted branch

    field :public_leaderboard_opted_out, :boolean, default: false

    field :browser_key_hash, :binary

    # The notification channel's address, and the proof its owner asked for it.

    # Nothing reads `notification_email` as a recipient on its own:

    # `OpenAgents.Notifications.EmailChannel.verified_address/1` is the one

    # read, and it returns `nil` while `notification_email_verified_at` is,

    # so an address typed but never confirmed is inert. The code is held as a

    # SHA-256 digest, never as plaintext.

    field :notification_email, :string

    field :notification_email_verified_at, :utc_datetime_usec

    field :notification_email_code_digest, :binary, redact: true

    field :notification_email_code_sent_at, :utc_datetime_usec

    field :notification_email_code_attempts, :integer, default: 0

    # Not a column: resolved once by `UserAuth.on_mount/4` when it builds the

    # scope, because the sidebar asks on every render and the answer must not

    # be a query each time. Defaults to false, so a user loaded by any other

          github_token_rotated_at: DateTime.t() | nil,

          public_leaderboard_opted_out: boolean(),

          browser_key_hash: binary() | nil,

          notification_email: String.t() | nil,

          notification_email_verified_at: DateTime.t() | nil,

          notification_email_code_digest: binary() | nil,

          notification_email_code_sent_at: DateTime.t() | nil,

          notification_email_code_attempts: non_neg_integer(),

          agent_surfaces?: boolean(),

          unread_notifications: non_neg_integer(),

          inserted_at: DateTime.t(),

       "account" => %{

         "id" => user.id,

         "github_login" => user.github_login,

         "github_name" => user.github_name

         "github_name" => user.github_name,

         # The one field on the account the person typed rather than the

         # provider supplied, so it is the one they are most likely to have

         # forgotten giving. Reported whether or not it was confirmed, because

         # the question a data export answers is what this deployment holds,

         # not what it would act on; the flag beside it says which.

         "notification_email" => user.notification_email,

         "notification_email_verified" =>

           not is_nil(OpenAgents.Notifications.EmailChannel.verified_address(user))

       },

       "identities" => identities_export(user, actor_links, refs),

       "bounds" => bounds(),

  @moduledoc """

  Drives an `email.delivery` effect to a terminal state.

  The payload carries the notification `dedupe_key` and optional `data`. When

  `data` does not contain a `to` recipient, the handler records a successful

  `nothing_to_send_to` terminal outcome. Otherwise it calls the configured

  `OpenAgents.Notifications.Delivery` adapter, which is a future seam: no real

  send happens unless a provider is configured.

  The payload names an account and an event. It does not name an address, and

  no caller can put one there: the recipient is resolved on the way out by

  `OpenAgents.Notifications.email_dispatch/1`, which returns an address only

  when the account confirmed it and asked for mail. An address that was typed

  and never confirmed is therefore unreachable from the queue as well as from

  the settings surface, and an account that switched the channel off between

  the enqueue and the send is not mailed on the strength of what it wanted

  earlier.

  A refusal is a completion, not a failure. Nothing about "this account has no

  confirmed address" improves by being tried again in eight seconds, so the

  effect records the reason and stops. Only a provider that could not be

  reached leaves the effect pending for the outbox to retry.

  """

  @behaviour OpenAgents.Effects.Handler

  alias OpenAgents.Effects.Effect

  alias OpenAgents.Notifications

  alias OpenAgents.Notifications.Delivery

  @impl OpenAgents.Effects.Handler

  def run(%Effect{payload: payload}, _idempotency_key) do

    data = Map.get(payload, "data", %{})

    case recipient(data) do

      nil ->

        {:ok, %{"outcome" => "nothing_to_send_to"}}

      to ->

        Delivery.adapter().deliver(to, data)

    end

  end

  defp recipient(data) when is_map(data) do

    case Map.get(data, "to") do

      value when is_binary(value) and value != "" -> value

      _ -> nil

    case Notifications.email_dispatch(payload) do

      {:ok, recipient, pointer} -> Delivery.adapter().deliver(recipient, pointer)

      {:refused, outcome} -> {:ok, %{"outcome" => outcome}}

    end

  end

end

  `OpenAgents.Repositories.readable_by/2` again, so a recipient who loses

  membership after the row was written stops seeing it.

  Delivery is in-product only. This deployment has no outbound mail path and

  accounts carry no email address, so an email channel would be a second,

  unconfigured system. Adding one means adding an address, an adapter, and a

  retry schedule, and belongs behind its own change.

  ## The second channel

  Delivery is in-product first and by email second. The inbox is the channel

  with no switch, because it is the product surface; email is off until an

  account confirms an address (`OpenAgents.Notifications.EmailChannel`) and

  turns `email_enabled` on, and it carries mentions only. A mention is the

  event addressed to one person by name and the lowest-volume category there

  is; the rest wait for a digest, because one message per comment on a busy

  issue is how a channel gets filtered to a folder nobody opens (#141).

  Email cannot inherit the durability the inbox gets for free. The record is

  written in the transaction, but the send is not, so `Delivery.enqueue/1`

  writes an `email.delivery` effect in that same transaction and

  `OpenAgents.Effects` owns the attempts. `email_dispatch/1` is the other half:

  it re-decides, at send time, everything the enqueue decided — confirmed

  address, channel, category, and the recipient's access to the repository — so

  a queued message cannot outlive the consent it was queued under.

  """

  import Ecto.Query, warn: false

  alias OpenAgents.Accounts.User

  alias OpenAgents.Issues.Comment

  alias OpenAgents.Issues.Issue

  alias OpenAgents.Notifications.Delivery

  alias OpenAgents.Notifications.EmailChannel

  alias OpenAgents.Notifications.IssueSubscription

  alias OpenAgents.Notifications.Mentions

  alias OpenAgents.Notifications.Notification

  @notifications_per_page 50

  # The kinds the email channel carries. One, deliberately. A mention names a

  # person, so it is the category whose volume is bounded by how often somebody

  # types your login; every other kind follows the traffic on a thread, and

  # mailing one message per comment is what a digest exists to avoid (#141).

  @email_kinds ["mention"]

  def per_page, do: @notifications_per_page

  ## Announcements

    |> Enum.filter(&enabled?(&1, kind))

    |> Enum.map(fn user ->

      insert_notification(user, issue, nil, kind, actor_login, dedupe_key)

      enqueue_email(user, issue, kind, actor_login, dedupe_key)

      user.id

    end)

  end

    |> Enum.filter(fn {user, _kind} -> readable?(repository, user) end)

    |> Enum.map(fn {user, kind} ->

      insert_notification(user, issue, comment, kind, actor_login, dedupe_key)

      enqueue_email(user, issue, kind, actor_login, dedupe_key)

      user.id

    end)

  end

  # The email half, asked for in the same transaction as the record it

  # announces. The four conditions are re-decided at send time by

  # `email_dispatch/1`; checking them here as well keeps the queue from filling

  # with effects for accounts that were never going to be mailed.

  defp enqueue_email(%User{} = user, %Issue{} = issue, kind, actor_login, dedupe_key) do

    if email_wanted?(user, kind) do

      Delivery.enqueue(

        dedupe_key: dedupe_key,

        user_id: user.id,

        issue_id: issue.id,

        kind: kind,

        actor_login: actor_login

      )

    end

    :ok

  end

  defp email_wanted?(%User{} = user, kind) do

    kind in @email_kinds and EmailChannel.deliverable?() and

      not is_nil(EmailChannel.verified_address(user)) and preferences(user).email_enabled

  end

  defp insert_notification(user, issue, comment, kind, actor_login, dedupe_key) do

    %Notification{}

    |> Notification.changeset(%{

    case existing do

      %Preference{id: nil} ->

        Repo.insert(changeset,

          on_conflict: {:replace, Preference.categories() ++ [:updated_at]},

          on_conflict: {:replace, Preference.switches() ++ [:updated_at]},

          conflict_target: [:user_id]

        )

  def preferences_recorded?(%User{} = user) do

    Repo.exists?(from preference in Preference, where: preference.user_id == ^user.id)

  end

  ## Outbound

  @doc """

  Resolves a queued `email.delivery` payload to a recipient and a pointer.

  Every question the enqueue answered is asked again here, against the database

  as it is now rather than as it was when the comment landed: is the account

  still active, is its address still confirmed, is the channel still on, is the

  category still on, and can it still read the repository. A queued message

  therefore cannot outlive the consent or the access it was queued under, which

  matters precisely because a sent message is the one notification no later

  authorization check can withdraw.

  A `{:refused, outcome}` is a completion, not a failure: none of these answers

  changes by being asked again in eight seconds. The outcome string is recorded

  on the effect, so the queue says why it sent nothing.

  The pointer carries what NOTIFY-001 lets a notification carry — the kind, the

  actor's login, the repository path, and the issue number — plus the two URLs

  a message needs to be useful. The issue's title is not in it.

  """

  @spec email_dispatch(map()) :: {:ok, String.t(), map()} | {:refused, String.t()}

  def email_dispatch(payload) when is_map(payload) do

    with {:ok, user} <- dispatch_user(payload["user_id"]),

         {:ok, address} <- dispatch_address(user),

         preferences = preferences(user),

         :ok <- dispatch_channel(preferences),

         :ok <- dispatch_category(preferences, payload["kind"]),

         {:ok, issue} <- dispatch_issue(payload["issue_id"]),

         {:ok, repository} <- dispatch_repository(issue, user) do

      {:ok, address, pointer(payload, issue, repository)}

    end

  end

  defp dispatch_user(user_id) when is_binary(user_id) do

    with {:ok, uuid} <- Ecto.UUID.cast(user_id),

         %User{status: "active"} = user <- Repo.get(User, uuid) do

      {:ok, user}

    else

      _absent -> {:refused, "recipient_gone"}

    end

  end

  defp dispatch_user(_user_id), do: {:refused, "recipient_gone"}

  defp dispatch_address(user) do

    case EmailChannel.verified_address(user) do

      nil -> {:refused, "no_verified_address"}

      address -> {:ok, address}

    end

  end

  defp dispatch_channel(%Preference{email_enabled: true}), do: :ok

  defp dispatch_channel(%Preference{}), do: {:refused, "channel_off"}

  defp dispatch_category(preferences, kind) when kind in @email_kinds do

    if category_enabled(preferences, kind), do: :ok, else: {:refused, "category_off"}

  end

  defp dispatch_category(_preferences, _kind), do: {:refused, "kind_not_carried"}

  # The issue's key is an integer, so the payload carries one and this reads it

  # back as one. Anything else is a payload this release did not write.

  defp dispatch_issue(issue_id) when is_integer(issue_id) do

    case Repo.get(Issue, issue_id) do

      %Issue{} = issue -> {:ok, issue}

      nil -> {:refused, "issue_gone"}

    end

  end

  defp dispatch_issue(_issue_id), do: {:refused, "issue_gone"}

  defp dispatch_repository(%Issue{repository_id: repository_id}, user) do

    repository = Repo.get(Repository, repository_id)

    if readable?(repository, user), do: {:ok, repository}, else: {:refused, "not_readable"}

  end

  defp pointer(payload, issue, repository) do

    base = String.trim_trailing(OpenAgentsWeb.Endpoint.url(), "/")

    path = "#{repository.owner}/#{repository.name}"

    %{

      "kind" => payload["kind"],

      "actor_login" => payload["actor_login"],

      "repository" => path,

      "issue_number" => issue.number,

      "url" => "#{base}/#{path}/issues/#{issue.number}",

      "settings_url" => "#{base}/notifications"

    }

  end

end

defmodule OpenAgents.Notifications.Delivery do

  @moduledoc """

  Durable outbound email delivery seam for notifications.

  The durable outbound half of a notification.

  Enqueues one `email.delivery` effect keyed to a notification `dedupe_key`.

  A recipient is optional in the caller's data; if none is provided the handler

  records a terminal `nothing_to_send_to` outcome instead of a failure.

  In-product delivery needs no queue: the record is written in the transaction

  that writes the comment it announces, so it exists exactly when the event

  does. Email cannot work that way. A send happens after that transaction

  commits and can fail on somebody else's server, so the asking has to be

  durable even though the doing is not.

  No real send happens here. The adapter is a future seam: the default

  `OpenAgents.Notifications.Delivery.NullAdapter` refuses unless a real

  provider is configured, and the caller supplies a `to` address.

  `enqueue/1` is called inside the same transaction as the notification row and

  writes one `email.delivery` effect. From there `OpenAgents.Effects` owns the

  schedule: a lease per attempt, exponential backoff between them, and a

  terminal `failed` at `maximum_attempts`. The effect's idempotency key is the

  recipient and the notification's `dedupe_key`, which is the same key the

  unique index on `notifications` uses, so a replayed fan-out produces one

  record and one send rather than two of each.

  ## What the payload may carry

  Identifiers, and no address. The recipient is resolved at send time by

  `OpenAgents.Notifications.email_dispatch/1` from the account's confirmed

  address, so a queued delivery cannot outlive the consent it was queued under:

  an account that removes its address, switches the channel off, or loses

  access to the repository stops being mailed, including for effects already

  sitting in the queue.

  """

  alias OpenAgents.Effects

  alias OpenAgents.Notifications.Notification

  @kind "email.delivery"

  @source_kind "notification"

  @doc """

  Enqueue an email delivery for a `Notification` or a bare `dedupe_key`.

  Enqueue the email half of one notification.

  Accepted shapes:

    * `%Notification{}`

    * a map or keyword with `:dedupe_key` and optional `:data`, `:user_id`,

      `:notification_id`, and `:maximum_attempts`

  When a `user_id` is known, the idempotency key is scoped to that user so the

  same `dedupe_key` for two different accounts stays two distinct deliveries.

  Requires `:dedupe_key`, `:user_id`, `:issue_id`, and `:kind`, and accepts

  `:actor_login` and `:maximum_attempts`. The idempotency key is scoped to the

  account, so the same event for two recipients is two deliveries.

  """

  @spec enqueue(Notification.t() | map() | keyword()) ::

          {:ok, Effects.Effect.t()} | {:error, term()}

  def enqueue(%Notification{} = notification) do

    enqueue(%{

      dedupe_key: notification.dedupe_key,

      user_id: notification.user_id,

      notification_id: notification.id,

      data: %{}

    })

  end

  @spec enqueue(map() | keyword()) :: {:ok, Effects.Effect.t()} | {:error, term()}

  def enqueue(attrs) when is_list(attrs), do: enqueue(Map.new(attrs))

  def enqueue(attrs) when is_map(attrs) do

    dedupe_key = fetch!(attrs, :dedupe_key)

    user_id = Map.get(attrs, :user_id)

    notification_id = Map.get(attrs, :notification_id)

    data = Map.get(attrs, :data) || %{}

    idempotency_source = if user_id, do: "#{user_id}/#{dedupe_key}", else: dedupe_key

    user_id = fetch!(attrs, :user_id)

    issue_id = fetch!(attrs, :issue_id)

    kind = fetch!(attrs, :kind)

    Effects.enqueue(@kind, %{

      payload: %{

        "dedupe_key" => dedupe_key,

        "user_id" => user_id,

        "notification_id" => notification_id,

        "data" => data

        "issue_id" => issue_id,

        "kind" => kind,

        "actor_login" => Map.get(attrs, :actor_login)

      },

      source_kind: @source_kind,

      source_id: dedupe_key,

      idempotency_key: Effects.idempotency_key(@kind, @source_kind, idempotency_source),

      idempotency_key: Effects.idempotency_key(@kind, @source_kind, "#{user_id}/#{dedupe_key}"),

      maximum_attempts: Map.get(attrs, :maximum_attempts, 5)

    })

  end

defmodule OpenAgents.Notifications.Delivery.MailerAdapter do

  @moduledoc """

  The delivery adapter that actually sends, through `OpenAgents.Mailer`.

  It is deliberately thin. Everything that decides whether a message may be

  sent — the confirmed address, the channel switch, the category, and the

  recipient's current access to the repository — is settled by

  `OpenAgents.Notifications.email_dispatch/1` before the adapter is reached, so

  this module has no authority to add or to withhold. It turns a resolved

  pointer into a message and reports what the provider said.

  A provider refusal comes back as `{:error, reason}`, which leaves the effect

  pending: the durable outbox counts the attempt, backs off, and stops at

  `maximum_attempts` with a terminal `failed`. That is the whole retry policy,

  and it lives in `OpenAgents.Effects` rather than here.

  """

  @behaviour OpenAgents.Notifications.Delivery.Adapter

  alias OpenAgents.Notifications.Email

  @impl true

  def deliver(recipient, data) when is_binary(recipient) do

    case Email.deliver_notification(recipient, data) do

      {:ok, _metadata} -> {:ok, %{"outcome" => "sent"}}

      {:error, reason} -> {:error, reason}

    end

  end

  def deliver(_recipient, _data), do: {:error, :no_recipient}

end

defmodule OpenAgents.Notifications.Delivery.NullAdapter do

  @moduledoc """

  Default no-op email delivery adapter.

  The adapter a deployment that configured none gets.

  No provider is configured, so a delivery that has a recipient cannot be sent.

  The handler returns an error and the durable outbox retries up to its

  `maximum_attempts`. A delivery without a recipient is handled before the

  adapter is ever called.

  It refuses every send, so a delivery that reached it — meaning the account

  confirmed an address and asked for mail — is retried by the durable outbox

  and then recorded as terminally failed rather than quietly dropped. A

  deployment in that state should be saying so on the settings surface too:

  `OpenAgents.Notifications.EmailChannel.deliverable?/0` is the switch that

  stops an address being collected in the first place.

  """

  @behaviour OpenAgents.Notifications.Delivery.Adapter

defmodule OpenAgents.Notifications.Email do

  @moduledoc """

  The two messages this application sends, and the mailer it sends them with.

  Both are plain text. A notification is a pointer with a link on it, which

  needs no layout, and a text part renders in every client without a fallback

  to maintain.

  ## What a notification message may say

  `NOTIFY-001` says a notification record stores identifiers, a kind, and the

  actor's login, never a title or a body. The message obeys the same rule for

  the same reason: it leaves the application, so it is the one copy of a

  notification that no later authorization check can withdraw. The repository

  path and the issue number travel because a link is useless without them and

  because the recipient's access to that repository was rechecked on the way

  out. The issue's title did not travel, and does not.

  ## Where they are sent from

  One `from` for both, configured under

  `OpenAgents.Notifications.EmailChannel`, so a deployment sets its sending

  identity in one place and no call site invents one.

  """

  import Swoosh.Email

  alias OpenAgents.Mailer

  alias OpenAgents.Notifications.EmailChannel

  @doc """

  Mails a verification code to an address nobody has confirmed yet.

  This is the one message that goes to an unverified address, and it is what

  makes verification possible at all. It carries the code and nothing about the

  account: an address typed by mistake learns that somebody asked, not who.

  """

  @spec deliver_verification(String.t(), String.t()) :: {:ok, term()} | {:error, term()}

  def deliver_verification(address, code) when is_binary(address) and is_binary(code) do

    new()

    |> to(address)

    |> from(EmailChannel.from())

    |> subject("Your OpenAgents verification code: #{code}")

    |> text_body("""

    Somebody asked to send OpenAgents notifications to this address.

    Your verification code is:

        #{code}

    Enter it on the notifications page to confirm the address. The code is good

    for 30 minutes.

    If this was not you, ignore this message. Nothing is sent to an address that

    has not been confirmed, so no further mail will arrive.

    """)

    |> Mailer.deliver()

  end

  @doc """

  Mails one notification to a confirmed address.

  `pointer` is what `OpenAgents.Notifications.email_dispatch/1` resolved: the

  kind, the actor's login, the repository path, the issue number, and the URL.

  Nothing else reaches this function, so nothing else can reach the message.

  """

  @spec deliver_notification(String.t(), map()) :: {:ok, term()} | {:error, term()}

  def deliver_notification(address, pointer) when is_binary(address) and is_map(pointer) do

    reference = "#{pointer["repository"]}##{pointer["issue_number"]}"

    new()

    |> to(address)

    |> from(EmailChannel.from())

    |> subject("#{headline(pointer)} on #{reference}")

    |> text_body("""

    #{headline(pointer)} on #{reference}.

    #{pointer["url"]}

    You are receiving this because email delivery is on for your account. Turn

    it off, or change the address, on the notifications page:

    #{pointer["settings_url"]}

    """)

    |> Mailer.deliver()

  end

  defp headline(%{"kind" => "mention", "actor_login" => login}) when is_binary(login),

    do: "#{login} mentioned you"

  defp headline(%{"kind" => "mention"}), do: "You were mentioned"

  defp headline(_pointer), do: "There is activity"

end

defmodule OpenAgents.Notifications.EmailChannel do

  @moduledoc """

  The address an account is willing to receive mail at, and the proof of it.

  ## Why the address is typed rather than taken

  GitHub OAuth can be asked for `user:email` and hand over whatever address the

  provider holds. This deployment does not ask. An address taken from a

  provider is an address nobody chose to give this application, and the first

  thing it would be used for is unsolicited mail to a mailbox its owner never

  named here. So the address is typed into the notification settings, by the

  person who wants mail, on purpose.

  ## The gate

  `verified_address/1` is the only function anything sends to, and it returns

  `nil` unless the account both names an address and confirmed it. Confirmation

  is a code mailed to the address and typed back, which is the only evidence

  this application can have that the person asking controls the mailbox.

  Three things make the gate hold rather than merely exist:

    * The code is held as a SHA-256 digest. A database read is not enough to

      claim somebody else's mailbox.

    * Guesses are counted and bounded at five. A short code with free guesses

      is not a secret.

    * The check constraint `users_notification_email_state_check` refuses a

      verified timestamp on a row with no address, so the gate survives a bug

      in this module.

  Changing the address clears the verification, because the evidence was about

  the old mailbox. Removing it clears everything, including the outstanding

  code.

  ## What a deployment without a mail provider does

  `deliverable?/0` reads one configuration key rather than inferring from the

  Swoosh adapter, because the inference is wrong in both directions: the local

  adapter is real delivery in development — the mailbox preview at

  `/dev/mailbox` — and it is a black hole in production. A deployment that

  configures no provider says so, and the settings surface offers no address

  field rather than accepting one it cannot mail to.

  """

  alias OpenAgents.Accounts.User

  alias OpenAgents.Notifications.Email

  alias OpenAgents.Repo

  # Long enough that five guesses are hopeless, short enough to retype from a

  # phone. Crockford's alphabet without I, L, O and U: no character in it can

  # be confused with another in a proportional font, and none of them spell

  # anything.

  @code_alphabet ~c"0123456789ABCDEFGHJKMNPQRSTVWXYZ"

  @code_length 8

  @code_lifetime_seconds 1_800

  @resend_after_seconds 60

  @maximum_attempts 5

  @typedoc "What the settings surface needs to render the address, and nothing more."

  @type state :: %{address: String.t() | nil, verified?: boolean(), pending?: boolean()}

  @typedoc "Why an address or a code was refused."

  @type refusal ::

          :not_deliverable

          | :invalid_address

          | :too_soon

          | :nothing_pending

          | :expired

          | :incorrect_code

          | :too_many_attempts

  @doc """

  The address this account may be mailed at, or `nil`.

  Every outbound notification resolves its recipient here. An address that was

  typed but never confirmed returns `nil`, which is what makes an unverified

  address unreachable rather than merely discouraged.

  """

  @spec verified_address(User.t() | nil) :: String.t() | nil

  def verified_address(%User{notification_email: address, notification_email_verified_at: at})

      when is_binary(address) and not is_nil(at),

      do: address

  def verified_address(_user), do: nil

  @doc "Whether this deployment can send at all. See the module note on `deliverable?/0`."

  @spec deliverable?() :: boolean()

  def deliverable?, do: Keyword.get(configuration(), :deliverable, false)

  @doc "The `{name, address}` every message this channel sends is from."

  @spec from() :: {String.t(), String.t()}

  def from, do: Keyword.fetch!(configuration(), :from)

  @doc """

  What the settings surface renders: the address, whether it is confirmed, and

  whether a code is outstanding.

  Never the code, and never its digest.

  """

  @spec state(User.t()) :: state()

  def state(%User{} = user) do

    %{

      address: user.notification_email,

      verified?: not is_nil(user.notification_email_verified_at),

      pending?: pending?(user)

    }

  end

  @doc """

  Records an address and mails a code to it.

  The address is inert until the code comes back. Re-recording the address an

  account already confirmed changes nothing rather than quietly unverifying it,

  because retyping what you already proved is not a withdrawal of the proof.

  """

  @spec set_address(User.t(), String.t()) :: {:ok, User.t()} | {:error, refusal()}

  def set_address(%User{} = user, address) when is_binary(address) do

    with :ok <- require_deliverable(),

         {:ok, normalized} <- normalize(address) do

      if normalized == verified_address(user) do

        {:ok, user}

      else

        issue_code(user, normalized)

      end

    end

  end

  @doc """

  Mails another code to the address already on the account.

  Bounded by `#{@resend_after_seconds}` seconds since the last one, so the send

  button cannot be turned into a way to mail somebody repeatedly. Issuing a new

  code retires the old one and resets the attempt count: the person is asking

  again, not guessing again.

  """

  @spec resend_code(User.t()) :: {:ok, User.t()} | {:error, refusal()}

  def resend_code(%User{notification_email: address} = user) when is_binary(address) do

    with :ok <- require_deliverable(),

         :ok <- require_resend_window(user),

         do: issue_code(user, address)

  end

  def resend_code(%User{}), do: {:error, :nothing_pending}

  @doc """

  Confirms the address with the code that was mailed to it.

  A correct code marks the address verified and clears the outstanding one, so

  the same code cannot be replayed. A wrong one counts, and at the fifth the

  code is retired entirely: the next step is a fresh send, not another guess.

  The comparison is constant-time over digests, so a caller cannot learn the

  code one character at a time.

  """

  @spec verify(User.t(), String.t()) :: {:ok, User.t()} | {:error, refusal()}

  def verify(%User{} = user, code) when is_binary(code) do

    with :ok <- require_pending(user),

         :ok <- require_unexpired(user),

         :ok <- require_attempts_left(user) do

      if Plug.Crypto.secure_compare(

           user.notification_email_code_digest,

           digest(normalize_code(code))

         ) do

        confirm(user)

      else

        count_failure(user)

      end

    end

  end

  @doc """

  Forgets the address, the verification, and any outstanding code.

  One update rather than a soft delete: there is nothing here worth keeping

  once the account has said to stop mailing it.

  """

  @spec remove_address(User.t()) :: {:ok, User.t()} | {:error, Ecto.Changeset.t()}

  def remove_address(%User{} = user) do

    update(user, %{

      notification_email: nil,

      notification_email_verified_at: nil,

      notification_email_code_digest: nil,

      notification_email_code_sent_at: nil,

      notification_email_code_attempts: 0

    })

  end

  ## Internals

  # The row and the message have to agree, and only one of them is

  # transactional. Writing first is the order that cannot mail a code the

  # database does not hold; rolling back on a refused send is what keeps the

  # other direction from mattering, so a provider hiccup while changing an

  # address does not leave the account with its previous verification quietly

  # withdrawn.

  defp issue_code(user, address) do

    code = generate_code()

    Repo.transaction(fn ->

      case update(user, %{

             notification_email: address,

             notification_email_verified_at: nil,

             notification_email_code_digest: digest(code),

             notification_email_code_sent_at: DateTime.utc_now(),

             notification_email_code_attempts: 0

           }) do

        {:ok, updated} ->

          case Email.deliver_verification(address, code) do

            {:ok, _delivery} -> updated

            {:error, _reason} -> Repo.rollback(:not_deliverable)

          end

        {:error, %Ecto.Changeset{}} ->

          Repo.rollback(:invalid_address)

      end

    end)

  end

  defp confirm(user) do

    update(user, %{

      notification_email_verified_at: DateTime.utc_now(),

      notification_email_code_digest: nil,

      notification_email_code_attempts: 0

    })

  end

  defp count_failure(user) do

    attempts = user.notification_email_code_attempts + 1

    attributes =

      if attempts >= @maximum_attempts do

        %{notification_email_code_digest: nil, notification_email_code_attempts: attempts}

      else

        %{notification_email_code_attempts: attempts}

      end

    case update(user, attributes) do

      {:ok, _updated} when attempts >= @maximum_attempts -> {:error, :too_many_attempts}

      {:ok, _updated} -> {:error, :incorrect_code}

      {:error, _changeset} -> {:error, :incorrect_code}

    end

  end

  defp update(user, attributes) do

    user

    |> Ecto.Changeset.change(attributes)

    |> Ecto.Changeset.check_constraint(:notification_email,

      name: :users_notification_email_state_check

    )