@spec check_dns([dns_record()], (charlist(), atom(), atom() -> list())) :: [
  checked_dns_record()
]

Live DNS re-check for a domain identity: resolves every expected DKIM CNAME, SPF TXT, and DMARC TXT record and reports pass/warn/missing per record.

expected_records is normally the output of dns_records_for/1 for the same identity. The resolver argument defaults to :inet_res.lookup/3 (an OTP built-in — no new dependency) and can be injected for testing or to point at a specific nameserver; it must accept the same three positional arguments :inet_res.lookup/3 does: (name_charlist, class, type), returning a list of answers (binaries for :txt — actually a list of character-list segments per TXT string, hence the flattening below — and a domain charlist for :cname).

Returns the same list dns_records_for/1 produced, each record augmented with :status (dns_check_result/0) and :found (the raw values seen at that name, for display — e.g. showing a user the CNAME they accidentally pointed elsewhere). This is a live, synchronous check: each record is one DNS query, so calling this for an identity with several DKIM tokens makes several queries. Safe to call from a "re-check DNS" button (SquatchMail.SES.recheck_identity/1,2 covers the SES-side verification status; this covers whether the records are actually visible in DNS, which can lag or be misconfigured independently of what SES has cached).

@spec client() :: {:ok, AWS.Client.t()} | {:error, :missing_credentials}

Builds an %AWS.Client{} from the current source row.

Loads the source via SquatchMail.Tracker.get_or_create_source/0. See client/1 — this returns the same {:ok, client} | {:error, :missing_credentials} shape.

@spec client(SquatchMail.Source.t()) ::
  {:ok, AWS.Client.t()} | {:error, :missing_credentials}

Builds an %AWS.Client{} from the given source.

For credentials_mode: "static" the source's access_key_id / secret_access_key are used. For "ambient" the standard AWS environment variables are read (see the moduledoc "Credentials" section). The client's HTTP backend is always the shared SquatchMail.Finch pool.

Returns {:error, :missing_credentials} — never raises — when required credentials aren't available. A fresh, unconfigured SquatchMail.Source is the normal state before a host has visited Base Camp, so this is an expected outcome every caller must handle, not an exceptional one: a LiveView calling sync_quota/1 or list_identities/1 against that source must be able to render "not connected yet" instead of crashing the handle_event/mount.

@spec create_identity(String.t()) ::
  {:ok, identity()} | {:error, :missing_credentials | term()}

Creates a new SES sending identity (domain or email address).

See create_identity/3. Builds the client from the current source.

@spec create_identity(String.t(), AWS.Client.t()) ::
  {:ok, identity()} | {:error, term()}

Creates a new SES sending identity, returning its normalized status.

For domains, the returned map's :dkim_tokens feed dns_records_for/1 to produce the DNS records the user must publish. For email addresses, SES sends a verification email and there are no DKIM tokens. Returns {:ok, identity} or a wrapped {:error, reason}.

@spec dns_records_for(identity()) :: [dns_record()]

Maps a normalized identity into the DNS records the user must publish.

Pure function — no network calls. For a domain identity it returns:

• one CNAME per DKIM token: <token>._domainkey.<domain> → <token>.<signing_hosted_zone> (the SES Easy DKIM pattern; the hosted zone comes from the identity's :dkim_signing_hosted_zone, defaulting to dkim.amazonses.com when absent),
• an SPF TXT record on the domain ("v=spf1 include:amazonses.com ~all"),
• a starter DMARC TXT record at _dmarc.<domain>.

For an email address identity there are no DNS records (SES verifies via a confirmation email), so an empty list is returned. Each record is a dns_record/0 map the dashboard can render as a table row.

@spec ensure_quota_synced(SquatchMail.Source.t() | nil) ::
  {:ok, SquatchMail.Source.t()} | {:error, :missing_credentials | term()}

Returns the source with a fresh quota, syncing from SES only when stale.

The cache is considered fresh for 6 hours. When quota_checked_at is nil or older than 6 hours, this calls sync_quota/2; otherwise it returns the current source unchanged in an {:ok, source} tuple. This is the ticket's "cache 6h" behaviour.

@spec list_identities() ::
  {:ok, [identity()]} | {:error, :missing_credentials | term()}

Lists SES sending identities for the current source. See list_identities/1.

@spec list_identities(AWS.Client.t()) :: {:ok, [identity()]} | {:error, term()}

Lists SES sending identities as normalized identity/0 maps.

Pages through AWS.SESv2.list_email_identities/4 (following NextToken) to collect the identity list, then fetches per-identity DKIM/verification detail via AWS.SESv2.get_email_identity/3 (the list response carries the verification status but not DKIM tokens, which the dashboard needs to render DNS guidance). Returns {:ok, identities} or a wrapped {:error, reason}.

@spec provision(String.t()) ::
  {:ok, SquatchMail.Source.t()} | {:error, :missing_credentials | term()}

Idempotently provisions SES event publishing for the current source.

See provision/3. Builds the client from the source itself.

@spec provision(SquatchMail.Source.t(), String.t(), AWS.Client.t()) ::
  {:ok, SquatchMail.Source.t()} | {:error, term()}

Idempotently provisions SES event publishing for source.

webhook_url must be the full, publicly-reachable HTTPS URL of SquatchMail's SNS webhook endpoint — typically https://<host>/<dashboard_path>/webhooks/sns/<webhook_token>. This module does not compute the host's public base URL (there is no router/endpoint at this layer); the dashboard/router layer is responsible for building it and passing it in.

The flow, each step a no-op if already satisfied:

1. Create (or reuse) a configuration set named source.configuration_set (a default derived from the configured prefix is used when blank).
2. Create (or reuse) an SNS topic. A stored source.sns_topic_arn is reused only after confirming the topic still exists (GetTopicAttributes); otherwise a new topic is created.
3. Subscribe webhook_url to the topic over HTTPS.
4. Create the configuration-set event destination pointing at the topic for all relevant SES event types.

On success the resolved configuration_set and sns_topic_arn are persisted back onto the source and {:ok, source} is returned. On failure a wrapped, actionable {:error, reason} is returned (never a raw AWS error map).

@spec quota_stale?(SquatchMail.Source.t()) :: boolean()

Returns true when the source's cached quota is missing or older than 6h.

@spec recheck_identity(String.t()) ::
  {:ok, identity()} | {:error, :missing_credentials | term()}

Re-queries a single identity's live verification/DKIM status from SES.

See recheck_identity/2. Builds the client from the current source.

@spec recheck_identity(String.t(), AWS.Client.t()) ::
  {:ok, identity()} | {:error, term()}

Re-queries a single identity's live verification/DKIM status from SES.

This always hits AWS.SESv2.get_email_identity/3 fresh (no caching) — the ticket's "live re-check". It re-asks SES for its own verification/DKIM determination rather than performing a raw DNS lookup: SES is the authority on whether an identity is usable for sending, and a passing DNS lookup that SES hasn't yet observed wouldn't let you send. (A supplementary :inet_res-based DNS resolver could confirm records resolve publicly; that's left as a dashboard-layer enhancement.) Returns {:ok, identity} or {:error, reason}.

@spec sync_quota() ::
  {:ok, SquatchMail.Source.t()} | {:error, :missing_credentials | term()}

Syncs the SES sending quota onto the current source, ignoring the cache.

See sync_quota/2.

@spec sync_quota(SquatchMail.Source.t(), AWS.Client.t()) ::
  {:ok, SquatchMail.Source.t()} | {:error, term()}

Fetches the SES account sending quota and persists it onto the source.

Calls AWS.SESv2.get_account/2, extracts the sending-enabled flag and the Max24HourSend / MaxSendRate / SentLast24Hours figures into the source's quota map, and stamps quota_checked_at. Returns {:ok, source} or a wrapped {:error, reason}.