@orieljs/framework 0.1.0-alpha.5 → 0.1.0-alpha.7

package/docs/verification.md

@@ -0,0 +1,152 @@
+# Email verification
+
+Ask new users to confirm their email address with a signed link before they reach the parts of your app that need it.
+The starter kits with pages do this already.
+
+## Introduction
+
+When a user registers, Oriel mails them a link. Opening it, while signed in, marks their address as verified, and the
+`verified` middleware keeps unverified users out of the routes you give it. The kits with pages use it for the
+dashboard (see [Email verification](starter-kits.md#email-verification) in the kits).
+
+### Model preparation
+
+A model built on `AuthenticatableModel`, as a new app's `User` is, can verify its email:
+
+- `hasVerifiedEmail()` tells you whether `email_verified_at` is set;
+- `markEmailAsVerified()` sets it to now and saves the model;
+- `getEmailForVerification()` returns the `email` attribute;
+- `sendEmailVerificationNotification()` mails the user the verification link.
+
+> [!NOTE]
+> In Laravel, only a `User` model that implements `MustVerifyEmail` gets the mail and is held back by `verified`, and
+> a new Laravel app's doesn't. In Oriel, every user model built on `AuthenticatableModel` can verify its email, so a
+> new user always gets the mail. Take `verified` off a route to let unverified users in.
+
+### Database preparation
+
+The `users` table needs an `email_verified_at` column, a nullable timestamp, which a new app's first migration has.
+
+## Routing
+
+Verification takes three routes, which the Inertia kits define in `routes/auth.ts`, behind the `auth` middleware: the
+notice that asks the user to verify, the link's handler, and a route that sends the link again.
+
+### The email verification notice
+
+The notice is the page a user sees when `verified` stops them. It is the `verification.notice` route,
+`/verify-email` in the kits:
+
+```ts title="routes/auth.ts"
+import { inertia, Route } from '@orieljs/framework'
+
+Route.middleware('auth').group(() => {
+  Route.get('verify-email', () => inertia('Auth/VerifyEmail')).name('verification.notice')
+})
+```
+
+The kits' notice sends a user who has verified on to the dashboard, and shows a "Resend verification email" button.
+
+### The email verification handler
+
+The link in the mail opens the `verification.verify` route, `/verify-email/{id}/{hash}`: the user's id, and the
+SHA-1 of their email address. The link is signed, and works for 60 minutes. Its route checks the signature with the
+`signed` middleware, and `EmailVerificationRequest` checks the `id` and `hash` against the signed-in user:
+
+```ts title="routes/auth.ts"
+import { EmailVerificationRequest, redirect, Route } from '@orieljs/framework'
+
+Route.get('verify-email/{id}/{hash}', async () => {
+  await EmailVerificationRequest.validate()
+  await new EmailVerificationRequest().fulfill()
+
+  return redirect().intended('/dashboard')
+})
+  .middleware(['auth', 'signed', 'throttle:6,1'])
+  .name('verification.verify')
+```
+
+`validate()` answers 403 when the link is for another user. `fulfill()` marks the email as verified and dispatches
+the `Verified` event, unless it was verified already. A link opened after it expired, or changed, gets a 403 from
+`signed`. The user must be signed in, so a user who opens the link in another browser signs in first, and is then sent
+back to it.
+
+The kits' handler is `VerifyEmailController`, which does the same and redirects to the dashboard with `?verified=1`.
+
+### Resending the verification email
+
+A user who lost the mail can ask for it again: the kits' `verification.send` route sends it, at most six times a
+minute:
+
+```ts title="routes/auth.ts"
+import { back, request, Route } from '@orieljs/framework'
+import type { User } from '../app/Models/User'
+
+Route.post('email/verification-notification', async () => {
+  const user = (await request().user<User>())!
+
+  await user.sendEmailVerificationNotification()
+
+  return back().with('status', 'verification-link-sent')
+})
+  .middleware(['auth', 'throttle:6,1'])
+  .name('verification.send')
+```
+
+In the Live kit, the `VerifyEmail` component's action sends it, with no rate limit of its own.
+
+### Protecting routes
+
+The `verified` middleware lets only verified users through:
+
+```ts title="routes/web.ts"
+import { Route, view } from '@orieljs/framework'
+
+Route.get('profile', () => view('profile')).middleware(['auth', 'verified'])
+```
+
+An unverified user is redirected to the `verification.notice` route, and to the page they wanted once they have
+verified. A request that wants JSON gets a 403, "Your email address is not verified.", instead. `verified:<route>`
+redirects to another named route, and with no `verification.notice` route the redirect goes to `/email/verify`. A
+guest gets the same redirect, so put `auth` first, as above.
+
+## Customization
+
+#### Verification email customization
+
+The mail is the `VerifyEmail` notification's: "Verify Email Address", a line asking the user to click the button, the
+button, and a closing line. It is sent in the styled template of [mail notifications](notifications.md), with a
+plain-text part. `VerifyEmail.toMailUsing()` builds the mail yourself, in a service provider's `boot()`. Its function
+receives the user and the signed link:
+
+```ts title="app/Providers/AppServiceProvider.ts"
+import { MailMessage, ServiceProvider, VerifyEmail } from '@orieljs/framework'
+
+export class AppServiceProvider extends ServiceProvider {
+  override boot(): void {
+    VerifyEmail.toMailUsing((notifiable, url) =>
+      new MailMessage()
+        .subject('Verify Email Address')
+        .line('Click the button below to verify your email address.')
+        .action('Verify Email Address', url),
+    )
+  }
+}
+```
+
+`VerifyEmail.createUrlUsing()` builds the link instead, for example for a client app on another domain, and
+`sendEmailVerificationUsing()` replaces the whole sending, with a function that receives the user.
+
+The link works for `auth.verification.expire` minutes, 60 unless your `config/auth.ts` sets it:
+
+```ts
+const auth = {
+  verification: { expire: 120 },
+}
+```
+
+## Events
+
+`Registered`, which the kits dispatch when a user signs up, sends the verification mail: Oriel listens for it with
+`SendEmailVerificationNotification`, which mails a user who hasn't verified. `fulfill()` and the kits' handler
+dispatch `Verified` once an address is verified. Listen for either, as for any [event](events.md).