@orieljs/framework 0.1.0-alpha.6 → 0.1.0-alpha.8

package/docs/authentication.md

@@ -0,0 +1,487 @@
+# Authentication
+
+Sign your users in with a session in the browser, or with API tokens, and keep guests out of the routes that need a
+user.
+
+## Introduction
+
+Oriel's authentication is built from **guards** and **providers**. A guard decides how a request's user is found: the
+`session` guard reads it from the session, and the `token` guard from an API token in the `Authorization` header. A
+provider decides how users are read from storage: the `eloquent` provider reads them with your `User` model.
+
+Both are set in `config/auth.ts`:
+
+```ts title="config/auth.ts"
+import { env } from '@orieljs/framework'
+import { User } from '../app/Models/User'
+
+export default {
+  defaults: { guard: env('AUTH_GUARD', 'web'), passwords: env('AUTH_PASSWORD_BROKER', 'users') },
+  guards: {
+    web: { driver: 'session', provider: 'users' },
+    token: { driver: 'token', provider: 'users', expiration: null },
+  },
+  providers: { users: { driver: 'eloquent', model: User } },
+  passwords: { users: { provider: 'users', table: 'password_reset_tokens', expire: 60, throttle: 60 } },
+  password_timeout: 10800,
+}
+```
+
+The `web` guard is the default. The provider names the model class itself, which the config file imports.
+
+### Starter kits
+
+Every [starter kit](starter-kits.md) comes with authentication: the kits with pages have registration, login, email
+verification, password reset and the settings pages, and the API kit has its token endpoints. Their code is in your
+app, so this page explains what it calls.
+
+### Database considerations
+
+A new app's `User` model is built on `AuthenticatableModel`, which signs users in by their `password` column, keeps
+"Remember me" tokens in `remember_token`, and uses `email` and `email_verified_at` for password resets and email
+verification. A new app's `users` table has these columns, with a `password` column long enough for a hash.
+
+```ts title="app/Models/User.ts"
+import { AuthenticatableModel, Authorizable, HasApiTokens, Model, Notifiable } from '@orieljs/framework'
+
+export class User extends HasApiTokens(Notifiable(Authorizable(AuthenticatableModel(Model)))) {}
+```
+
+> [!NOTE]
+> Laravel's `User` model extends `Illuminate\Foundation\Auth\User`, and adds traits such as `HasApiTokens` and
+> `Notifiable`. Oriel's builds the same abilities from mixins: `AuthenticatableModel` for signing in, `Authorizable`
+> for [authorization](authorization.md), `Notifiable` for [notifications](notifications.md) and `HasApiTokens` for
+> [API tokens](#api-tokens).
+
+## Authentication quickstart
+
+### Retrieving the authenticated user
+
+`Auth.user()` returns the signed-in user, or `undefined` for a guest. It is async, since the guard may have to read
+the session or the database the first time it is asked:
+
+```ts
+const user = await Auth.user<User>()
+
+const id = await Auth.id()
+```
+
+`request().user()` does the same for the current request, through the request's guard:
+
+```ts title="app/Http/Controllers/FlightController.ts"
+import { request } from '@orieljs/framework'
+import type { User } from '../../Models/User'
+import { Controller } from './Controller'
+
+export class FlightController extends Controller {
+  /** Update the flight information for an existing flight. */
+  async update() {
+    const user = await request().user<User>()
+
+    // ...
+
+    return { updatedBy: user?.id }
+  }
+}
+```
+
+The type you give is a cast, not a check. On a route behind the `auth` middleware, a user is there, so you can write
+`(await request().user<User>())!`.
+
+> [!WARNING]
+> `request().user()` returns a promise, so `await` it every time. TypeScript flags `if (request().user())`, but not
+> `!request().user()` or `request().user() === undefined`, which are always `false`.
+
+> [!NOTE]
+> Laravel's `Auth::user()` and `$request->user()` return the user at once. Oriel's return a promise: `await` them.
+
+#### Determining if the current user is authenticated
+
+`Auth.check()` tells you whether a user is signed in, and `Auth.guest()` whether no one is. Both are async:
+
+```ts
+if (await Auth.check()) {
+  // The user is logged in...
+}
+```
+
+To keep guests out of a route, use the `auth` middleware rather than checking in each action.
+
+### Protecting routes
+
+The `auth` middleware lets only signed-in users reach a route:
+
+```ts title="routes/web.ts"
+import { Route } from '@orieljs/framework'
+
+Route.get('/flights', () => {
+  // Only authenticated users may access this route...
+  return 'Flights'
+}).middleware('auth')
+```
+
+#### Redirecting unauthenticated users
+
+A guest who reaches a route behind `auth` is redirected to `/login`, and back to the page they wanted once they sign
+in. A request that wants JSON gets a 401 instead, `{ "message": "Unauthenticated." }`. `redirectGuestsTo()` in
+`bootstrap/app.ts` sends guests elsewhere (see
+[Redirecting guests and signed-in users](middleware.md#redirecting-guests-and-signed-in-users)).
+
+#### Redirecting authenticated users
+
+The `guest` middleware does the opposite: it sends a signed-in user away from the pages meant for guests, such as the
+login page. It sends them to your `dashboard` route, else your `home` route, else `/`; `redirectUsersTo()` in
+`bootstrap/app.ts` chooses another place.
+
+#### Specifying a guard
+
+`auth` takes the guards to try, by name. The first one that has a user lets the request through, and becomes the
+request's guard, so `Auth.user()` and `request().user()` read from it:
+
+```ts
+Route.get('/flights', () => 'Flights').middleware('auth:token')
+
+Route.get('/account', () => 'Account').middleware('auth:web,token')
+```
+
+### Login throttling
+
+The kits' login stops a user after five failed attempts for the same email address and IP address, for a minute, and
+dispatches the `Lockout` event. The limit is in their `LoginRequest` (in the Live kit, the `Login` component), written
+with the `RateLimiter` (see [Rate limiting](cache.md#rate-limiting)).
+
+## Manually authenticating users
+
+You don't have to use the kits' code. `Auth.attempt()` signs a user in with their credentials:
+
+```ts title="app/Http/Controllers/LoginController.ts"
+import { Auth, back, redirect, request } from '@orieljs/framework'
+import { Controller } from './Controller'
+
+export class LoginController extends Controller {
+  /** Handle an authentication attempt. */
+  async authenticate() {
+    const credentials = await request().validate({
+      email: 'required|email',
+      password: 'required',
+    })
+
+    if (await Auth.attempt(credentials)) {
+      await request().session().regenerate()
+
+      return redirect().intended('dashboard')
+    }
+
+    return back()
+      .withErrors({ email: 'The provided credentials do not match our records.' })
+      .withInput(request().only('email'))
+  }
+}
+```
+
+`attempt()` finds the user by every credential except those whose key contains `password`, here by `email`, then
+checks the password against the user's hash. When it matches, it signs the user in and returns `true`; otherwise it
+returns `false`. `redirect().intended()` sends the user to the page they wanted before `auth` sent them to the login
+page, or to the path you give.
+
+`attempt()` changes the session's id as it signs the user in, which protects against session fixation; the kits also
+call `regenerate()`, as above.
+
+#### Specifying additional conditions
+
+Add any condition to the credentials. A list matches any of its values, and a function receives the query:
+
+```ts
+declare const email: string
+declare const password: string
+// ---cut---
+if (await Auth.attempt({ email, password, active: 1 })) {
+  // Authentication was successful...
+}
+
+if (await Auth.attempt({ email, password, role: ['admin', 'editor'] })) {
+  // ...
+}
+
+if (await Auth.attempt({ email, password, verified: (query: { whereNotNull(column: string): unknown }) => query.whereNotNull('email_verified_at') })) {
+  // ...
+}
+```
+
+#### Accessing specific guard instances
+
+`Auth.guard()` returns a guard by name, with the same methods:
+
+```ts
+const user = await Auth.guard('token').user()
+```
+
+### Remembering users
+
+Pass `true` as `attempt()`'s second argument to keep the user signed in after their session ends, until they sign
+out:
+
+```ts
+declare const email: string
+declare const password: string
+declare const remember: boolean
+// ---cut---
+if (await Auth.attempt({ email, password }, remember)) {
+  // The user is being remembered...
+}
+```
+
+Oriel then sets a "Remember me" cookie, which lasts 400 days unless the guard's `remember` setting, in minutes, says
+otherwise. `Auth.viaRemember()` tells you whether the current user was signed in by that cookie. Signing out
+changes the user's `remember_token`, so the cookie stops working on every browser.
+
+### Other authentication methods
+
+#### Authenticate a user instance
+
+`Auth.login()` signs in a user you already have, such as one who has registered. Its second argument remembers the user:
+
+```ts
+declare const user: User
+// ---cut---
+await Auth.login(user)
+
+await Auth.login(user, true)
+```
+
+#### Authenticate a user by ID
+
+`Auth.loginUsingId()` signs in the user with that primary key, and returns them, or `false` when there is none:
+
+```ts
+await Auth.loginUsingId(1)
+```
+
+#### Authenticate a user once
+
+`Auth.once()` signs a user in for the current request only: nothing is written to the session, and no cookie is set:
+
+```ts
+declare const credentials: { email: string; password: string }
+// ---cut---
+if (await Auth.once(credentials)) {
+  // ...
+}
+```
+
+`attempt()`, `once()`, `login()`, `loginUsingId()` and `logout()` need a guard that keeps a user, such as `web`, and
+throw on the `token` guard.
+
+> [!NOTE]
+> Laravel also has HTTP Basic authentication (`auth.basic`). Oriel doesn't.
+
+## Logging out
+
+`Auth.logout()` signs the user out. Invalidate their session and make a new CSRF token too, then redirect them:
+
+```ts title="app/Http/Controllers/LogoutController.ts"
+import { Auth, redirect, request } from '@orieljs/framework'
+import { Controller } from './Controller'
+
+export class LogoutController extends Controller {
+  /** Log the user out of the application. */
+  async logout() {
+    await Auth.logout()
+
+    await request().session().invalidate()
+
+    request().session().regenerateToken()
+
+    return redirect('/')
+  }
+}
+```
+
+> [!NOTE]
+> Laravel's `logoutOtherDevices()` and its password confirmation pages (`password.confirm`) aren't in Oriel.
+
+## API tokens
+
+A client that isn't a browser, such as a mobile app or another service, signs in with an API token. Oriel's tokens are
+Laravel Sanctum's personal access tokens, under the `token` guard: Sanctum's `auth:sanctum` is `auth:token` here. A new
+app has the `personal_access_tokens` table, and its `User` model has `HasApiTokens`.
+
+### Issuing tokens
+
+`createToken()` makes a token for the user, with a name. The token's plain text is shown only once, so return it to the
+client and keep nothing else. Here a user signed in in the browser makes one, from a web route:
+
+```ts title="routes/web.ts"
+import { Auth, request, Route } from '@orieljs/framework'
+import type { User } from '../app/Models/User'
+
+Route.post('/tokens/create', async () => {
+  const user = (await Auth.user<User>())!
+  const token = await user.createToken(request().string('token_name').toString())
+
+  return { token: token.plainTextToken }
+}).middleware('auth')
+```
+
+The client sends it with every request, in the `Authorization` header:
+
+```text
+Authorization: Bearer 1|Zb3qL9vXw2Kc7Ty4NfRm8HpAs6Ud1GeJo5WiYtBn
+```
+
+The token is its row's id, a `|` and a random secret; the table keeps only the secret's SHA-256.
+
+### Protecting routes
+
+Put the routes behind `auth:token`. The API kit does, for its routes in `routes/api.ts`:
+
+```ts title="routes/api.ts"
+import { request, Route } from '@orieljs/framework'
+
+Route.middleware('auth:token').group(() => {
+  Route.get('/user', () => request().user())
+})
+```
+
+A request with no token, a wrong one or an expired one gets a 401, `{ "message": "Unauthenticated." }`, when it asks for
+JSON, as API clients do; the API kit answers JSON under `/api` whatever the request asks for. Each request with a token
+updates its `last_used_at`.
+
+### Token abilities
+
+A token can be limited to some abilities, which you list when you make it. A token made without a list has every
+ability:
+
+```ts
+declare const user: User
+// ---cut---
+const token = await user.createToken('token-name', ['server:update'])
+```
+
+In a request made with a token, `user.tokenCan()` tells you whether the token has an ability, and `tokenCant()`
+whether it hasn't:
+
+```ts
+const user = (await request().user<User>())!
+
+if (user.tokenCan('server:update')) {
+  // ...
+}
+```
+
+### Token expiration
+
+A token can expire: give `createToken()` a date as its third argument. The `token` guard's `expiration`, in minutes,
+ends every token that long after it was made; `null`, in a new app, leaves them to their own date.
+
+```ts
+declare const user: User
+// ---cut---
+const token = await user.createToken('token-name', ['*'], new Date(Date.now() + 7 * 24 * 60 * 60 * 1000))
+```
+
+### Revoking tokens
+
+`currentAccessToken()` is the token of the current request, and `tokens()` gives all of the user's tokens. Delete a
+token to revoke it:
+
+```ts
+const user = (await request().user<User>())!
+
+// Revoke the token that was used to authenticate the current request...
+await user.currentAccessToken()?.delete()
+
+// Revoke all tokens...
+for (const token of await user.tokens()) {
+  await token.delete()
+}
+```
+
+> [!NOTE]
+> Laravel Sanctum's `tokens()` is a relation, so `$user->tokens()->delete()` revokes them all with one query. Oriel's
+> returns the tokens as an array: delete each one. Sanctum's SPA cookie authentication isn't in Oriel: a browser app
+> served by your app signs in with the `web` guard, and a route can accept both with `auth:web,token`.
+
+## Adding custom guards
+
+`Auth.extend()` adds a guard driver, in a service provider's `boot()`. Its function receives the guard's name and its
+entry of `config/auth.ts`, and returns an object with the `Guard` contract's methods:
+
+```ts title="app/Providers/AppServiceProvider.ts"
+// @filename: app/Services/Auth/JwtGuard.ts
+import type { Guard } from '@orieljs/framework/contracts'
+export declare class JwtGuard implements Guard {
+  constructor(name: string)
+  user: Guard['user']
+  id: Guard['id']
+  check: Guard['check']
+  guest: Guard['guest']
+  validate: Guard['validate']
+  hasUser: Guard['hasUser']
+  setUser: Guard['setUser']
+}
+// ---cut---
+import { Auth, ServiceProvider } from '@orieljs/framework'
+import { JwtGuard } from '../Services/Auth/JwtGuard'
+
+export class AppServiceProvider extends ServiceProvider {
+  override boot(): void {
+    Auth.extend('jwt', (name) => new JwtGuard(name))
+  }
+}
+```
+
+Then name the driver in a guard of `config/auth.ts`: `api: { driver: 'jwt', provider: 'users' }`.
+
+## Adding custom user providers
+
+`Auth.provider()` adds a user provider driver, for users kept somewhere your models don't reach. Its function
+receives the provider's entry of `config/auth.ts` and returns an object with the `UserProvider` contract's methods:
+`retrieveById()`, `retrieveByToken()`, `updateRememberToken()`, `retrieveByCredentials()` and
+`validateCredentials()`:
+
+```ts title="app/Providers/AppServiceProvider.ts"
+// @filename: app/Extensions/MongoUserProvider.ts
+import type { UserProvider } from '@orieljs/framework/contracts'
+export declare class MongoUserProvider implements UserProvider {
+  constructor(connection: unknown)
+  retrieveById: UserProvider['retrieveById']
+  retrieveByToken: UserProvider['retrieveByToken']
+  updateRememberToken: UserProvider['updateRememberToken']
+  retrieveByCredentials: UserProvider['retrieveByCredentials']
+  validateCredentials: UserProvider['validateCredentials']
+}
+// ---cut---
+import { Auth, ServiceProvider } from '@orieljs/framework'
+import { MongoUserProvider } from '../Extensions/MongoUserProvider'
+
+export class AppServiceProvider extends ServiceProvider {
+  override boot(): void {
+    Auth.provider('mongo', (config) => new MongoUserProvider(config.connection))
+  }
+}
+```
+
+Then use it in `config/auth.ts`: `providers: { users: { driver: 'mongo', connection: 'mongodb' } }`.
+
+## Automatic password rehashing
+
+When a user signs in with `attempt()` and their password's hash was made with other settings than your current ones,
+such as fewer bcrypt rounds, Oriel hashes the password again and saves it. Turn this off with `rehash_on_login: false`
+in `config/hashing.ts` (see [Hashing](hashing.md)).
+
+## Events
+
+Signing in and out dispatches these events, which you can [listen](events.md) for:
+
+| Event | When |
+| --- | --- |
+| `Attempting` | `attempt()` or `once()` is about to check credentials |
+| `Validated` | The credentials matched |
+| `Failed` | The credentials didn't match |
+| `Login` | A user signed in with `attempt()`, `login()`, `loginUsingId()` or the "Remember me" cookie (`once()` dispatches none) |
+| `Logout` | A user signed out |
+| `Lockout` | The kits' login throttle stopped a user |
+| `Registered` | The kits registered a user (it sends the verification mail) |
+| `Verified` | A user verified their email address |
+| `PasswordReset` | The kits reset a user's password |