Wire up Oban, email change, error pages, CSP, readiness, DB SSL

Six production-readiness fixes to the template:

- Oban: start it in the supervision tree, add the jobs-table migration,
  and ship a reference worker (it was configured but never running, so
  enqueuing a job would have crashed).
- Email change: link-confirmed flow with a confirmation link to the new
  address and a heads-up to the old one. Adds a `sent_to` token column,
  Accounts.request_email_change/3 + apply_email_change/2, a Settings
  section, and i18n.
- Error UX: branded, self-contained 404/500 pages and a top-level React
  ErrorBoundary keyed on the Inertia page.
- Content-Security-Policy: nonce + strict-dynamic in prod, a relaxed
  dev profile for LiveReload/LiveDashboard, and a :csp_extra_sources
  config seam for third-party origins.
- Health: add a /health/ready readiness probe that checks the DB pool
  (the existing /health stays a cheap liveness probe).
- DB SSL: on by default in prod (verify_peer + SNI from DATABASE_URL),
  opt out with DATABASE_SSL=false.

Author: andreogle

assets/js/app.tsx

@@ -4,6 +4,7 @@ import { createInertiaApp, router } from '@inertiajs/react';
 import { createElement, StrictMode } from 'react';
 import { createRoot } from 'react-dom/client';
 import { AppProviders } from './app-providers';
+import ErrorBoundary from './components/ErrorBoundary';
 import { syncLocale } from './components/LocaleSync';
 import Toaster from './components/Toaster';
 import { toast } from './components/toast';
@@ -60,7 +61,12 @@ createInertiaApp({
             long-lived (sockets, caches, listeners) survives route changes. */}
         <App {...props}>
           {({ Component, props: pageProps, key }) => (
-            <AppProviders>{createElement(Component, { key: key ?? undefined, ...pageProps })}</AppProviders>
+            <AppProviders>
+              {/* Keyed on the page key so navigation remounts the boundary
+                  and clears any caught error — long-lived providers above
+                  stay mounted. */}
+              <ErrorBoundary key={key ?? undefined}>{createElement(Component, pageProps)}</ErrorBoundary>
+            </AppProviders>
           )}
         </App>
         <Toaster />

assets/js/components/ErrorBoundary.tsx

@@ -0,0 +1,57 @@
+import { Component, type ErrorInfo, type ReactNode } from 'react';
+import { useTranslation } from 'react-i18next';
+import Button from './Button';
+
+interface Props {
+  children: ReactNode;
+}
+
+interface State {
+  hasError: boolean;
+}
+
+/**
+ * Top-level client error boundary. Catches render-time exceptions
+ * thrown by a page (or anything below it) so a single broken component
+ * shows a branded fallback instead of a blank white screen.
+ *
+ * In `app.tsx` it's keyed on the Inertia page key, so navigating to a
+ * different page remounts it and clears the error automatically — the
+ * user can recover by clicking a link without a full reload.
+ *
+ * This is the one place the project's "no raw try/catch" rule doesn't
+ * apply: React error boundaries are the supported synchronous catch-all
+ * for the render tree, with no Promise to route through `go()`.
+ */
+export default class ErrorBoundary extends Component<Props, State> {
+  state: State = { hasError: false };
+
+  static getDerivedStateFromError(): State {
+    return { hasError: true };
+  }
+
+  componentDidCatch(error: Error, info: ErrorInfo) {
+    // Surface to the console in every environment. Wire your error
+    // monitoring SDK (Sentry, AppSignal, …) in here.
+    console.error('Unhandled render error:', error, info.componentStack);
+  }
+
+  render() {
+    if (this.state.hasError) return <ErrorFallback />;
+    return this.props.children;
+  }
+}
+
+function ErrorFallback() {
+  const { t } = useTranslation();
+
+  return (
+    <div role="alert" className="flex min-h-screen flex-col items-center justify-center gap-4 p-6 text-center">
+      <h1 className="text-2xl font-semibold">{t('error.title')}</h1>
+      <p className="max-w-md text-sm text-gray-600 dark:text-gray-400">{t('error.body')}</p>
+      <Button type="button" onClick={() => window.location.reload()}>
+        {t('error.reload')}
+      </Button>
+    </div>
+  );
+}

assets/js/i18n/locales/en.ts

@@ -16,6 +16,11 @@ export default {
     themeDark: 'Dark',
     themeSystem: 'System',
   },
+  error: {
+    title: 'Something went wrong',
+    body: 'An unexpected error occurred. Try reloading the page — if it keeps happening, please come back in a little while.',
+    reload: 'Reload',
+  },
   home: {
     welcome: 'Welcome to ElixirReactStarter',
     stack: 'Phoenix 1.8 · Inertia.js · React · SSR',
@@ -32,6 +37,13 @@ export default {
   },
   settings: {
     title: 'Settings',
+    changeEmail: {
+      title: 'Change email',
+      current: 'Your current email is {{email}}.',
+      newEmail: 'New email',
+      currentPassword: 'Current password',
+      submit: 'Send confirmation link',
+    },
     changePassword: {
       title: 'Change password',
       warning: 'Updating your password will log you out of any other devices.',

assets/js/i18n/locales/es.ts

@@ -16,6 +16,11 @@ export default {
     themeDark: 'Oscuro',
     themeSystem: 'Sistema',
   },
+  error: {
+    title: 'Algo salió mal',
+    body: 'Ocurrió un error inesperado. Intenta recargar la página; si el problema persiste, vuelve a intentarlo más tarde.',
+    reload: 'Recargar',
+  },
   home: {
     welcome: 'Bienvenido a ElixirReactStarter',
     stack: 'Phoenix 1.8 · Inertia.js · React · SSR',
@@ -32,6 +37,13 @@ export default {
   },
   settings: {
     title: 'Ajustes',
+    changeEmail: {
+      title: 'Cambiar correo electrónico',
+      current: 'Tu correo electrónico actual es {{email}}.',
+      newEmail: 'Nuevo correo electrónico',
+      currentPassword: 'Contraseña actual',
+      submit: 'Enviar enlace de confirmación',
+    },
     changePassword: {
       title: 'Cambiar contraseña',
       warning: 'Cambiar tu contraseña cerrará tu sesión en los demás dispositivos.',

assets/js/pages/Settings.tsx

@@ -1,4 +1,4 @@
-import { useForm } from '@inertiajs/react';
+import { useForm, usePage } from '@inertiajs/react';
 import { useState } from 'react';
 import { useTranslation } from 'react-i18next';
 import {
@@ -22,13 +22,77 @@ export default function Settings() {
     <AppLayout title={t('settings.title')}>
       <div className="max-w-xl space-y-12">
         <h1 className="text-2xl font-semibold">{t('settings.title')}</h1>
+        <ChangeEmailSection />
         <ChangePasswordSection />
         <DeleteAccountSection />
       </div>
     </AppLayout>
   );
 }
 
+function ChangeEmailSection() {
+  const { t } = useTranslation();
+  const currentEmail = usePage().props.current_user?.email ?? '';
+  const { data, setData, put, processing, errors, reset } = useForm({
+    current_password: '',
+    email: '',
+  });
+
+  return (
+    <section className="space-y-4">
+      <header>
+        <h2 className="text-lg font-medium">{t('settings.changeEmail.title')}</h2>
+        <p className="text-sm text-gray-600 dark:text-gray-400">
+          {t('settings.changeEmail.current', { email: currentEmail })}
+        </p>
+      </header>
+      <form
+        onSubmit={(e) => {
+          e.preventDefault();
+          put('/settings/email', { onSuccess: () => reset() });
+        }}
+        className="space-y-4"
+      >
+        <div>
+          <label htmlFor="new_email" className="block text-sm mb-1">
+            {t('settings.changeEmail.newEmail')}
+          </label>
+          <input
+            id="new_email"
+            type="email"
+            autoComplete="email"
+            value={data.email}
+            onChange={(e) => setData('email', e.target.value)}
+            className={inputClass}
+            required
+          />
+          {errors.email && <p className="mt-1 text-sm text-red-600">{errors.email}</p>}
+        </div>
+
+        <div>
+          <label htmlFor="email_current_password" className="block text-sm mb-1">
+            {t('settings.changeEmail.currentPassword')}
+          </label>
+          <input
+            id="email_current_password"
+            type="password"
+            autoComplete="current-password"
+            value={data.current_password}
+            onChange={(e) => setData('current_password', e.target.value)}
+            className={inputClass}
+            required
+          />
+          {errors.current_password && <p className="mt-1 text-sm text-red-600">{errors.current_password}</p>}
+        </div>
+
+        <Button type="submit" disabled={processing}>
+          {t('settings.changeEmail.submit')}
+        </Button>
+      </form>
+    </section>
+  );
+}
+
 function ChangePasswordSection() {
   const { t } = useTranslation();
   const { data, setData, put, processing, errors, reset } = useForm({

config/prod.exs

@@ -13,6 +13,12 @@ config :elixir_react_starter, ElixirReactStarterWeb.Endpoint,
 # cookie must never travel over plain HTTP.
 config :elixir_react_starter, session_secure: true
 
+# Strict Content-Security-Policy in production: nonce + strict-dynamic
+# for scripts, no framing, first-party only. Add third-party origins via
+# :csp_extra_sources rather than loosening this. Dev/test default to the
+# relaxed profile so LiveReload / LiveDashboard keep working.
+config :elixir_react_starter, content_security_policy: :strict
+
 # Force using SSL in production. This also sets the "strict-security-transport" header,
 # known as HSTS. If you have a health check endpoint, you may want to exclude it below.
 # Note `:force_ssl` is required to be set at compile-time.

config/runtime.exs

@@ -32,9 +32,38 @@ if config_env() == :prod do
 
   maybe_ipv6 = if System.get_env("ECTO_IPV6") in ~w(true 1), do: [:inet6], else: []
 
+  database_url = get_env!.("DATABASE_URL")
+
+  # Encrypt the DB connection by default. Production traffic to a managed
+  # Postgres almost always crosses a network boundary, so TLS is on
+  # unless explicitly disabled with DATABASE_SSL=false (e.g. a sidecar
+  # proxy that already encrypts, or local-socket access).
+  #
+  # We verify the server certificate against the OS trust store and pin
+  # the hostname (SNI) parsed from DATABASE_URL — so a MITM with a valid
+  # cert for some *other* host can't intercept. Providers whose cert
+  # chains aren't in the system store (some managed PG offer a private
+  # CA) need either their CA added to the OS trust store or DATABASE_SSL=false.
+  db_ssl =
+    if System.get_env("DATABASE_SSL", "true") in ~w(true 1) do
+      db_host = URI.parse(database_url).host || ""
+
+      [
+        verify: :verify_peer,
+        cacerts: :public_key.cacerts_get(),
+        server_name_indication: to_charlist(db_host),
+        depth: 3,
+        # Refuse to connect if the chain can't be verified, rather than
+        # silently downgrading to an unauthenticated session.
+        customize_hostname_check: [match_fun: :public_key.pkix_verify_hostname_match_fun(:https)]
+      ]
+    else
+      false
+    end
+
   config :elixir_react_starter, ElixirReactStarter.Repo,
-    # ssl: true,
-    url: get_env!.("DATABASE_URL"),
+    ssl: db_ssl,
+    url: database_url,
     pool_size: String.to_integer(System.get_env("POOL_SIZE") || "10"),
     # For machines with several cores, consider starting multiple pools of `pool_size`
     # pool_count: 4,

lib/elixir_react_starter/accounts.ex

@@ -10,8 +10,9 @@ defmodule ElixirReactStarter.Accounts do
 
   Generated CRUD helpers come from `use ElixirReactStarter.Context`. The custom
   functions here cover registration, the session lifecycle, email
-  confirmation, password reset, authenticated password change, and
-  account deletion (the last two re-verify the current password).
+  confirmation, password reset, the link-confirmed email change, the
+  authenticated password change, and account deletion (the last three
+  re-verify the current password).
 
   The `User` schema is deliberately minimal — email, hashed password,
   locale, confirmed_at. Add profile fields (name, avatar, …) per project.
@@ -160,6 +161,98 @@ defmodule ElixirReactStarter.Accounts do
     |> log_result("Email confirmed for user #{user.id}")
   end
 
+  # =============================================================================
+  # Email change (authenticated, link-confirmed)
+  # =============================================================================
+  @doc """
+  Starts an email change after re-verifying the current password.
+
+  Validates the new address (format, length, not unchanged, not already
+  taken) and, on success, issues a single-use `email_change` token whose
+  `sent_to` holds the pending address. Returns `{:ok, raw_token}` — the
+  caller mails the confirmation link to the *new* address and notifies
+  the *old* one. The user's email isn't touched until they click the
+  link (`apply_email_change/2`).
+
+  Returns `{:error, :invalid_password}` or `{:error, changeset}`.
+  """
+  def request_email_change(user, current_password, new_email) do
+    if User.valid_password?(user, current_password) do
+      user
+      |> User.email_changeset(%{email: new_email})
+      |> validate_email_change()
+      |> case do
+        %{valid?: true} ->
+          Repo.delete_all(UserToken.delete_user_tokens_by_context_query(user.id, "email_change"))
+          {raw_token, user_token} = UserToken.build_email_change_token(user, new_email)
+          Repo.insert!(user_token)
+          Logger.info("Email change requested for user #{user.id}")
+          {:ok, raw_token}
+
+        changeset ->
+          {:error, %{changeset | action: :update}}
+      end
+    else
+      Logger.warning("Failed email change attempt for user #{user.id}: incorrect password")
+      {:error, :invalid_password}
+    end
+  end
+
+  @doc """
+  Applies a pending email change. Verifies the `email_change` token
+  belongs to `user` and hasn't expired, then swaps in the address it
+  was issued for. The DB unique index is the final guard against the
+  address being claimed between request and click (TOCTOU). Consumes
+  every email-change token for the user on success.
+
+  Returns `{:ok, user}`, `{:error, :invalid_token}`, or
+  `{:error, changeset}`.
+  """
+  def apply_email_change(user, raw_token) do
+    query = UserToken.verify_email_change_token_query(raw_token, user.id)
+
+    case Repo.one(query) do
+      %UserToken{sent_to: new_email} ->
+        user
+        |> User.email_changeset(%{email: new_email})
+        |> Repo.update()
+        |> case do
+          {:ok, updated} ->
+            Repo.delete_all(
+              UserToken.delete_user_tokens_by_context_query(user.id, "email_change")
+            )
+
+            Logger.info("Email changed for user #{user.id}")
+            {:ok, updated}
+
+          {:error, _changeset} = error ->
+            error
+        end
+
+      nil ->
+        {:error, :invalid_token}
+    end
+  end
+
+  # Layers the checks `User.email_changeset/2` can't express on its own:
+  # the address must actually differ and must not already belong to
+  # another account.
+  defp validate_email_change(changeset) do
+    cond do
+      not changeset.valid? ->
+        changeset
+
+      Ecto.Changeset.get_change(changeset, :email) == nil ->
+        Ecto.Changeset.add_error(changeset, :email, "is the same as your current email")
+
+      get_user_by(email: Ecto.Changeset.get_change(changeset, :email)) ->
+        Ecto.Changeset.add_error(changeset, :email, "has already been taken")
+
+      true ->
+        changeset
+    end
+  end
+
   # =============================================================================
   # Password change (authenticated)
   # =============================================================================