@orieljs/framework 0.1.0-alpha.12 → 0.1.0-alpha.13

package/dist/jsx-runtime.js

@@ -2,9 +2,9 @@ import {
   Fragment,
   jsx,
   jsxs
-} from "./chunk-24673JQF.js";
-import "./chunk-MURTCTRH.js";
-import "./chunk-HTJKT2R2.js";
+} from "./chunk-ZRTWDJKD.js";
+import "./chunk-6GMXKQ6O.js";
+import "./chunk-CKH4KCYF.js";
 export {
   Fragment,
   jsx,

package/dist/{testing-CKwfWJGn.d.ts → testing-B8NOiQC9.d.ts}

@@ -1357,6 +1357,11 @@ declare class LiveComponentManager implements LiveManager {
 
 /** The URI the client runtime posts updates to. */
 declare const UPDATE_URI = "/oriel/live/update";
+/**
+ * Where the client gets a session before its first update when the page came without one (a page cached at a CDN):
+ * through the `web` middleware, so the answer sets the session and XSRF-TOKEN cookies (Sanctum's csrf-cookie route).
+ */
+declare const SESSION_URI = "/oriel/live/session";
 /**
  * Binds the LiveManager and the PaginationState that WithPagination components answer, merges the `live` config,
  * registers POST /oriel/live/update (named `live.update`, in the `web` group: sessions and CSRF apply), the upload and
@@ -1583,4 +1588,4 @@ interface PaginationProps {
  */
 declare function Pagination({ paginator, class: className }: PaginationProps): Htmlable;
 
-export { type DatabaseTestOptions as $, UploadValidationError as A, BusFake as B, Component as C, WithPagination as D, EventFake as E, FileNotPreviewableError as F, componentName as G, live as H, InvalidLiveRequestError as I, persistentMiddleware as J, AnonymousNotifiable as K, Live as L, MailFake as M, NotificationFake as N, On as O, PERSISTENT_MIDDLEWARE as P, QueueFake as Q, AssertableInertia as R, StorageFake as S, TEMPORARY_UPLOAD_DEFAULTS as T, UPDATE_URI as U, AssertableJson as V, WithFileUploads as W, type BatchRecord as X, type BootOptions as Y, type CountOrFilter as Z, DatabaseMigrations as _, type ComponentResult as a, DatabaseTransactions as a0, type DispatchedEvent as a1, type ExpectedErrors as a2, type ExpectedListener as a3, FakeDisk as a4, FakeFile as a5, HttpClient as a6, InteractsWithApplication as a7, InteractsWithConsole as a8, InteractsWithDatabase as a9, cookiePrefix as aA, decryptCookie as aB, encryptCookie as aC, flatten as aD, freezeSecond as aE, freezeTime as aF, guessMimeType as aG, inertiaPageOf as aH, install as aI, isExpired as aJ, matches as aK, nameOf as aL, recordingExceptionHandler as aM, recordingViewFactory as aN, responseCookies as aO, runCommand as aP, travel as aQ, travelBack as aR, travelTo as aS, usingInMemoryDatabase as aT, InteractsWithTime as aa, type JsonStructure as ab, MailRecord as ac, MakesHttpRequests as ad, PendingCommand as ae, type PushedJob as af, RefreshDatabase as ag, RefreshDatabaseState as ah, type RequestData as ai, type RequestOptions as aj, type ResponseContext as ak, type ResponseCookie as al, type SentNotification as am, TESTING_ENVIRONMENT as an, type TableOrModel as ao, type Target as ap, TestCase as aq, type TestHooks as ar, TestResponse as as, type TestTrait as at, type TravelDate as au, Wormhole as av, actingAsAuthFactory as aw, addresses as ax, applyEnvironment as ay, cookieHeader as az, Computed as b, CorruptComponentPayloadError as c, ErrorBag as d, InvalidUploadSignatureError as e, LiveComponentManager as f, LiveComponentNotFoundError as g, LiveError as h, type LiveProps as i, LiveServiceProvider as j, Locked as k, MethodNotCallableError as l, PREVIEW_URI as m, type Paginated as n, Pagination as o, type PaginationProps as p, type PaginationSource as q, PendingEvent as r, type PersistentMiddleware as s, PropertyNotUpdatableError as t, type TemporaryFileData as u, TemporaryFileNotFoundError as v, TemporaryUploadedFile as w, TestRequestScope as x, Testable as y, UPLOAD_URI as z };
+export { DatabaseMigrations as $, UPLOAD_URI as A, BusFake as B, Component as C, UploadValidationError as D, EventFake as E, FileNotPreviewableError as F, WithPagination as G, componentName as H, InvalidLiveRequestError as I, live as J, persistentMiddleware as K, Live as L, MailFake as M, NotificationFake as N, On as O, PERSISTENT_MIDDLEWARE as P, QueueFake as Q, AnonymousNotifiable as R, StorageFake as S, TEMPORARY_UPLOAD_DEFAULTS as T, UPDATE_URI as U, AssertableInertia as V, WithFileUploads as W, AssertableJson as X, type BatchRecord as Y, type BootOptions as Z, type CountOrFilter as _, type ComponentResult as a, type DatabaseTestOptions as a0, DatabaseTransactions as a1, type DispatchedEvent as a2, type ExpectedErrors as a3, type ExpectedListener as a4, FakeDisk as a5, FakeFile as a6, HttpClient as a7, InteractsWithApplication as a8, InteractsWithConsole as a9, cookieHeader as aA, cookiePrefix as aB, decryptCookie as aC, encryptCookie as aD, flatten as aE, freezeSecond as aF, freezeTime as aG, guessMimeType as aH, inertiaPageOf as aI, install as aJ, isExpired as aK, matches as aL, nameOf as aM, recordingExceptionHandler as aN, recordingViewFactory as aO, responseCookies as aP, runCommand as aQ, travel as aR, travelBack as aS, travelTo as aT, usingInMemoryDatabase as aU, InteractsWithDatabase as aa, InteractsWithTime as ab, type JsonStructure as ac, MailRecord as ad, MakesHttpRequests as ae, PendingCommand as af, type PushedJob as ag, RefreshDatabase as ah, RefreshDatabaseState as ai, type RequestData as aj, type RequestOptions as ak, type ResponseContext as al, type ResponseCookie as am, type SentNotification as an, TESTING_ENVIRONMENT as ao, type TableOrModel as ap, type Target as aq, TestCase as ar, type TestHooks as as, TestResponse as at, type TestTrait as au, type TravelDate as av, Wormhole as aw, actingAsAuthFactory as ax, addresses as ay, applyEnvironment as az, Computed as b, CorruptComponentPayloadError as c, ErrorBag as d, InvalidUploadSignatureError as e, LiveComponentManager as f, LiveComponentNotFoundError as g, LiveError as h, type LiveProps as i, LiveServiceProvider as j, Locked as k, MethodNotCallableError as l, PREVIEW_URI as m, type Paginated as n, Pagination as o, type PaginationProps as p, type PaginationSource as q, PendingEvent as r, type PersistentMiddleware as s, PropertyNotUpdatableError as t, SESSION_URI as u, type TemporaryFileData as v, TemporaryFileNotFoundError as w, TemporaryUploadedFile as x, TestRequestScope as y, Testable as z };

package/dist/testing.d.ts

@@ -1,3 +1,3 @@
-export { K as AnonymousNotifiable, R as AssertableInertia, V as AssertableJson, X as BatchRecord, Y as BootOptions, B as BusFake, Z as CountOrFilter, _ as DatabaseMigrations, $ as DatabaseTestOptions, a0 as DatabaseTransactions, a1 as DispatchedEvent, E as EventFake, a2 as ExpectedErrors, a3 as ExpectedListener, a4 as FakeDisk, a5 as FakeFile, a6 as HttpClient, a7 as InteractsWithApplication, a8 as InteractsWithConsole, a9 as InteractsWithDatabase, aa as InteractsWithTime, ab as JsonStructure, L as Live, M as MailFake, ac as MailRecord, ad as MakesHttpRequests, N as NotificationFake, ae as PendingCommand, af as PushedJob, Q as QueueFake, ag as RefreshDatabase, ah as RefreshDatabaseState, ai as RequestData, aj as RequestOptions, ak as ResponseContext, al as ResponseCookie, am as SentNotification, S as StorageFake, an as TESTING_ENVIRONMENT, ao as TableOrModel, ap as Target, aq as TestCase, ar as TestHooks, as as TestResponse, at as TestTrait, y as Testable, au as TravelDate, av as Wormhole, aw as actingAsAuthFactory, ax as addresses, ay as applyEnvironment, az as cookieHeader, aA as cookiePrefix, aB as decryptCookie, aC as encryptCookie, aD as flatten, aE as freezeSecond, aF as freezeTime, aG as guessMimeType, aH as inertiaPageOf, aI as install, aJ as isExpired, aK as matches, aL as nameOf, aM as recordingExceptionHandler, aN as recordingViewFactory, aO as responseCookies, aP as runCommand, aQ as travel, aR as travelBack, aS as travelTo, aT as usingInMemoryDatabase } from './testing-CKwfWJGn.js';
+export { R as AnonymousNotifiable, V as AssertableInertia, X as AssertableJson, Y as BatchRecord, Z as BootOptions, B as BusFake, _ as CountOrFilter, $ as DatabaseMigrations, a0 as DatabaseTestOptions, a1 as DatabaseTransactions, a2 as DispatchedEvent, E as EventFake, a3 as ExpectedErrors, a4 as ExpectedListener, a5 as FakeDisk, a6 as FakeFile, a7 as HttpClient, a8 as InteractsWithApplication, a9 as InteractsWithConsole, aa as InteractsWithDatabase, ab as InteractsWithTime, ac as JsonStructure, L as Live, M as MailFake, ad as MailRecord, ae as MakesHttpRequests, N as NotificationFake, af as PendingCommand, ag as PushedJob, Q as QueueFake, ah as RefreshDatabase, ai as RefreshDatabaseState, aj as RequestData, ak as RequestOptions, al as ResponseContext, am as ResponseCookie, an as SentNotification, S as StorageFake, ao as TESTING_ENVIRONMENT, ap as TableOrModel, aq as Target, ar as TestCase, as as TestHooks, at as TestResponse, au as TestTrait, z as Testable, av as TravelDate, aw as Wormhole, ax as actingAsAuthFactory, ay as addresses, az as applyEnvironment, aA as cookieHeader, aB as cookiePrefix, aC as decryptCookie, aD as encryptCookie, aE as flatten, aF as freezeSecond, aG as freezeTime, aH as guessMimeType, aI as inertiaPageOf, aJ as install, aK as isExpired, aL as matches, aM as nameOf, aN as recordingExceptionHandler, aO as recordingViewFactory, aP as responseCookies, aQ as runCommand, aR as travel, aS as travelBack, aT as travelTo, aU as usingInMemoryDatabase } from './testing-B8NOiQC9.js';
 import './contracts.js';
 import './index.d-WQpfdIbG.js';

package/dist/testing.js

@@ -52,9 +52,9 @@ import {
   travelBack,
   travelTo,
   usingInMemoryDatabase
-} from "./chunk-7NA4HALO.js";
-import "./chunk-MURTCTRH.js";
-import "./chunk-HTJKT2R2.js";
+} from "./chunk-OTCTQVDQ.js";
+import "./chunk-6GMXKQ6O.js";
+import "./chunk-CKH4KCYF.js";
 export {
   AnonymousNotifiable,
   AssertableInertia,

package/docs/authentication.md

@@ -187,6 +187,8 @@ 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.
 
+To ask for a code after the password, by email or from an authenticator app, see [Two-factor login](two-factor.md).
+
 #### Specifying additional conditions
 
 Add any condition to the credentials. A list matches any of its values, and a function receives the query:

package/docs/console.md

@@ -116,7 +116,7 @@ These are the commands every app has. A new app adds one of its own, `inspire`,
 | `schedule:run` | Runs the scheduled tasks that are due |
 | `schedule:work` | Runs the tasks that are due, every minute, until you stop it |
 | `storage:link` | Links `public/storage` to `storage/app/public` |
-| `vercel:build` | Writes your app's build for Vercel into `.vercel/output` ([Deploying to Vercel](deployment.md#deploying-to-vercel)) |
+| `vercel:build` | Writes your app's build for Vercel into `.vercel/output` ([Deploying to Vercel](deployment.md#deploying-to-vercel)); `--cron=` sets when Vercel calls the scheduler ([Scheduled tasks](deployment.md#scheduled-tasks)) |
 
 `node oriel help <command>` lists a command's options. A few that are worth knowing up front:
 

package/docs/deployment.md

@@ -308,10 +308,11 @@ and each instance has its own, so:
   headers itself, so the function trusts them when `trusted_proxies`, in `config/http.ts`, is empty: your URLs keep
   the browser's `https`, and `request().ip()` is the visitor's (see
   [Configuring trusted proxies](requests.md#configuring-trusted-proxies)).
-- **Files your app stores** go on an `s3` disk (see [File storage](storage.md)): the `local` and `public` disks write
-  into `storage`, which the function can't.
-- **No queue worker or scheduler runs.** With `QUEUE_CONNECTION=sync`, a job runs during the request that dispatches
-  it.
+- **Files your app stores** go on the `blob` disk, a Vercel Blob store, or an `s3` disk (see
+  [The Vercel Blob driver](storage.md#the-vercel-blob-driver)): the `local` and `public` disks write into `storage`,
+  which the function can't.
+- **No queue worker runs.** With `QUEUE_CONNECTION=sync`, a job runs during the request that dispatches it. Your
+  scheduled tasks run through Vercel Cron (see [Scheduled tasks](#scheduled-tasks)).
 - **Inertia pages render in the browser**, as they do when no SSR server answers: the SSR server doesn't run on
   Vercel. `INERTIA_SSR_ENABLED=false` skips asking it.
 
@@ -331,7 +332,26 @@ Route.get('/pricing', () => view('pricing'))
 
 `cache.headers` leaves a response that sets a cookie alone, so that the CDN never hands one visitor's cookies to the
 next. The `web` group's `StartSession` and `VerifyCsrfToken` set cookies on every page: take them off the pages you
-cache, as above. Those pages have no session, so they can't show who is signed in.
+cache, as above. Those pages have no session, so they can't show who is signed in. Their Live components still work:
+they get a session with their first update (see [Pages cached without a session](live.md#pages-cached-without-a-session)).
+
+### Scheduled tasks
+
+No `schedule:work` runs on Vercel, so Vercel Cron calls your app's scheduler instead. When your app schedules any task,
+`vercel:build` adds a cron that calls `/_oriel/schedule`, daily at 03:00 UTC. Add a `CRON_SECRET` to the project's
+environment variables (a long random string): Vercel sends it with every call, and without it the route answers 404,
+so nobody else can run your tasks.
+
+Each call runs every task that fell due since the previous call, once, however often it fell due in between: a task
+scheduled every five minutes runs once a day, and a task at 04:00 runs at the next morning's call. `vercel:build` names
+the tasks due more often than the cron. Vercel's Hobby plan runs a cron at most once a day, sometime within the hour
+you chose; a paid plan can call more often:
+
+```sh
+node oriel vercel:build --cron="*/10 * * * *"
+```
+
+`--cron=false` writes no cron.
 
 ## Debug mode
 

package/docs/live.md

@@ -689,6 +689,26 @@ export default class PostCount extends Component {
 `lazy={false}` turns `static lazy` off. Without `placeholder()`, the placeholder is the `live.lazy_placeholder` view,
 or an empty `<div>`. Give the placeholder the same root element as `render()`.
 
+## Pages cached without a session
+
+A page that is the same for every visitor can be cached by a CDN (see
+[Caching pages on the CDN](deployment.md#caching-pages-on-the-cdn)), and its Live components still work. Such a page
+leaves `StartSession` and `VerifyCsrfToken` out, so it comes with no session and no `XSRF-TOKEN` cookie. Before its
+first update, the client asks `/oriel/live/session` for both, once for the whole page, and then sends the update with
+the token:
+
+```ts title="routes/web.ts"
+import { Route, StartSession, VerifyCsrfToken, view } from '@orieljs/framework'
+
+Route.get('/docs/{page}', (page: string) => view('docs', { page }))
+  .middleware('cache.headers:public;s_maxage=86400;stale_while_revalidate=60')
+  .withoutMiddleware(StartSession, VerifyCsrfToken)
+```
+
+The cached HTML is the same for everyone, so render nothing there that belongs to one visitor: no name, no flashed
+message, no CSRF field. A lazy component suits such a page: its placeholder is cached, and what it shows for this
+visitor comes with its own load. `Live.start({ sessionUri })` moves the session route if you moved the update route.
+
 ## Pagination
 
 `WithPagination` gives a component a page, which `paginate()` uses:

package/docs/navigation.json

@@ -151,6 +151,10 @@
           "slug": "authentication",
           "title": "Authentication"
         },
+        {
+          "slug": "two-factor",
+          "title": "Two-factor login"
+        },
         {
           "slug": "authorization",
           "title": "Authorization"

package/docs/routing.md

@@ -431,7 +431,7 @@ yourself. Until the first run, any name is accepted.
 Your [Inertia](inertia.md#links-and-the-route-helper) pages build URLs with the same `route()`, from your adapter. It
 takes the same names and parameters, and returns a path. The browser's route table leaves out the routes that
 `types.except_routes` in `config/inertia.ts` names, with `*` as a wildcard. Unless you set it, it leaves out `live.*`,
-Live's own routes.
+Live's own routes, and `vercel.*`, the route Vercel Cron calls.
 
 ```tsx tab="React" title="resources/js/components/PostLink.tsx"
 import { Link, route } from '@orieljs/inertia-react'

package/docs/scheduling.md

@@ -219,6 +219,9 @@ Add one cron entry to your server, which runs `schedule:run` every minute:
 `schedule:run` runs each due task once, prints its name, and goes on to the next one when a task fails, after
 printing the error. With nothing due, it prints "No scheduled commands are ready to run.".
 
+On Vercel, which runs no cron of yours, Vercel Cron calls the scheduler instead (see
+[Scheduled tasks on Vercel](deployment.md#scheduled-tasks)).
+
 ### Sub-minute tasks
 
 A task that runs every few seconds, such as `everyTenSeconds()`, is due every minute. Its `schedule:run` runs it

package/docs/storage.md

@@ -5,9 +5,9 @@ service), through one API.
 
 ## Configuration
 
-Your disks are in `config/filesystems.ts`. Each disk names its driver, `local` or `s3`, and its settings; `default`
-names the disk `Storage` uses when you don't name one (`FILESYSTEM_DISK`, else `local`). A new app has three disks:
-`local`, `public` and `s3`.
+Your disks are in `config/filesystems.ts`. Each disk names its driver, `local`, `s3` or `vercel-blob`, and its
+settings; `default` names the disk `Storage` uses when you don't name one (`FILESYSTEM_DISK`, else `local`). A new app
+has four disks: `local`, `public`, `s3` and `blob`.
 
 ### The local driver
 
@@ -40,6 +40,27 @@ The `s3` disk reads `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_DEFAULT_R
 `AWS_ENDPOINT` and `AWS_USE_PATH_STYLE_ENDPOINT` from your `.env`. For an S3-compatible service, such as MinIO or
 Cloudflare R2, set `endpoint`, and `usePathStyleEndpoint` if it wants the bucket in the path.
 
+### The Vercel Blob driver
+
+On Vercel, files your app stores need a disk that outlives the function: the `blob` disk keeps them in a
+[Vercel Blob](https://vercel.com/docs/vercel-blob) store. Create a store in your Vercel project's Storage tab and
+connect it to the project: Vercel then sets `BLOB_READ_WRITE_TOKEN`, which the disk reads.
+
+```ts
+import { Storage } from '@orieljs/framework'
+declare const cover: Uint8Array
+// ---cut---
+await Storage.disk('blob').put('covers/launch.png', cover)
+
+const address = Storage.disk('blob').url('covers/launch.png')
+```
+
+`url()` gives the file's public address in the store, worked out from the token; set `BLOB_URL` to use another one
+(a custom domain). `root` (`BLOB_ROOT`) keeps every path under a folder, so preview deployments can write under
+`preview` and never touch production's files. Blob stores here are public: a `private` disk or file is refused, and
+`temporaryUrl()` returns the public address. A Vercel function accepts request bodies up to 4.5 MB, which limits what
+a form can upload through it.
+
 ## Obtaining disk instances
 
 `Storage` works on the default disk; `Storage.disk(name)` on another:

package/docs/two-factor.md

@@ -0,0 +1,183 @@
+# Two-factor login
+
+Ask for a second factor after the password: a 6-digit code sent by email, or one from an authenticator app, with
+one-time recovery codes for when the phone or the mailbox is gone.
+
+## Introduction
+
+With two-factor login on, a correct password no longer signs the user in. It starts a pending login, kept in the
+session, and your app shows a page that asks for the code. Only the right code (or a recovery code) completes the
+login. This is Laravel Fortify's two-factor login, with an emailed code as well.
+
+Each user has a method:
+
+- **Email**, the default: a code is mailed to the user when their password is accepted. It needs no setup, so every
+  user has it from the start.
+- **Authenticator app**: the user scans a QR code with an app such as Google Authenticator or 1Password and confirms
+  it with one code; from then on, the app's code is asked for.
+
+The starter kits don't have two-factor pages yet: you add the routes and pages your app needs, as below.
+
+## Turning it on
+
+Add the four columns two-factor login keeps on `users`, then turn it on in `config/auth.ts`:
+
+```sh
+node oriel two-factor:install
+node oriel migrate
+```
+
+```ts title="config/auth.ts"
+import { User } from '../app/Models/User'
+// ---cut---
+export default {
+  defaults: { guard: 'web', passwords: 'users' },
+  guards: { web: { driver: 'session', provider: 'users' } },
+  providers: { users: { driver: 'eloquent', model: User } },
+  two_factor: { enabled: true },
+}
+```
+
+`two_factor` takes these settings, each with its default:
+
+| Setting | Default | |
+| --- | --- | --- |
+| `enabled` | `false` | Ask for a second factor after the password |
+| `methods` | `['email', 'app']` | The methods users may use (see below) |
+| `default` | `'email'` | The method a user has until they set up another |
+| `code_ttl` | `600` | Seconds an emailed code works |
+| `pending_ttl` | `600` | Seconds a pending login waits for its code |
+| `max_attempts` | `5` | Wrong codes a pending login allows; then the user signs in again |
+| `resend_after` | `30` | Seconds before another email code may be sent |
+| `window` | `1` | Authenticator steps (30 seconds each) of clock drift accepted either way |
+| `recovery_codes` | `8` | How many recovery codes a user gets |
+| `issuer` | `app.name` | The name authenticator apps show |
+
+A user is asked only by a method open to them: email, or an app they have set up. With `methods: ['app']`, a user who
+hasn't set up an app has no method open, so their password alone signs them in, as in Fortify, where two-factor is each
+user's choice. Keep `'email'` in `methods` to ask every user for a second factor.
+
+The secret and the recovery codes are encrypted with your app key; emailed codes are kept hashed, in the cache, so the
+cache must be shared by your servers (`database` or `redis`, as on Vercel).
+
+## Signing in
+
+Your login controller calls `TwoFactor.attempt()` instead of `Auth.attempt()`. It has three outcomes: `'authenticated'`
+(the user is signed in: two-factor is off, or not asked of this user), `'challenge'` (the password was right and the
+code is asked for), and `false` (wrong credentials):
+
+```ts title="app/Http/Controllers/LoginController.ts"
+import { back, redirect, request, TwoFactor } from '@orieljs/framework'
+import { Controller } from './Controller'
+
+export class LoginController extends Controller {
+  async authenticate() {
+    const credentials = await request().validate({ email: 'required|email', password: 'required' })
+
+    const result = await TwoFactor.attempt(credentials, request().boolean('remember'))
+    if (result === 'challenge') return redirect('/two-factor-challenge')
+    if (result === 'authenticated') {
+      await request().session().regenerate()
+      return redirect().intended('dashboard')
+    }
+
+    return back().withErrors({ email: 'The provided credentials do not match our records.' }).withInput(request().only('email'))
+  }
+}
+```
+
+## The challenge page
+
+The challenge page's routes take the `two-factor.challenge` middleware: only a login waiting for its code reaches them,
+and anyone else is sent to log in.
+
+```ts title="routes/web.ts"
+import { back, redirect, request, Route, TwoFactor, view } from '@orieljs/framework'
+
+Route.middleware('two-factor.challenge').group(() => {
+  Route.get('/two-factor-challenge', async () => view('auth.two-factor', { challenge: await TwoFactor.challenge() }))
+
+  Route.post('/two-factor-challenge', async () => {
+    if (await TwoFactor.verify(String(request().input('code', '')))) {
+      await request().session().regenerate()
+      return redirect().intended('dashboard')
+    }
+    return back().withErrors({ code: 'That code is not right.' })
+  })
+
+  Route.post('/two-factor-challenge/email', async () => {
+    await TwoFactor.useMethod('email')
+    return back()
+  })
+
+  Route.post('/two-factor-challenge/resend', async () => {
+    return back().with('status', (await TwoFactor.resend()) ? 'We sent you a new code.' : 'Wait a moment before asking again.')
+  })
+})
+```
+
+`TwoFactor.challenge()` gives the page what to say: the method asked for, the other methods the user has (`methods`),
+and where an emailed code went, masked (`a***@example.com`). `verify()` takes the 6-digit code for that method, or a
+recovery code, read leniently: spaces, dashes and capitals don't matter. A code works once; five wrong codes end the
+pending login, and the user signs in again.
+
+The emailed code is the `TwoFactorCode` notification, sent with your mailer, so on Vercel your app needs a mail service
+over SMTP. `TwoFactorCode.toMailUsing()` lets you write the mail yourself:
+
+```ts title="app/Providers/AppServiceProvider.ts"
+import { MailMessage, TwoFactorCode } from '@orieljs/framework'
+// ---cut---
+TwoFactorCode.toMailUsing((_user, code, minutes) =>
+  new MailMessage().subject('Your sign-in code').line(`Your code is ${code}.`).line(`It works for ${minutes} minutes.`),
+)
+```
+
+## Setting up an authenticator app
+
+On an account page, a signed-in user sets up their app in two steps: show the QR code, then confirm with a code from
+the app. Until it is confirmed, the app doesn't count, and the user is still asked by email:
+
+```ts title="routes/web.ts"
+import { back, request, Route, TwoFactor, view } from '@orieljs/framework'
+import type { User } from '../app/Models/User'
+// ---cut---
+Route.middleware('auth').group(() => {
+  Route.post('/account/two-factor/app', async () => {
+    const { svg, secret } = await TwoFactor.enableApp((await request().user<User>())!)
+    return view('account.two-factor-app', { svg, secret })
+  })
+
+  Route.post('/account/two-factor/app/confirm', async () => {
+    const confirmed = await TwoFactor.confirmApp((await request().user<User>())!, String(request().input('code', '')))
+    return confirmed ? back().with('status', 'Your app is set up.') : back().withErrors({ code: 'That code is not right.' })
+  })
+})
+```
+
+`enableApp()` returns the secret (for typing in by hand), its `otpauth://` URL and the QR code as an SVG image.
+`confirmApp()` makes the app the user's method and gives them recovery codes. `disableApp()` removes it, and
+`setMethod()` lets a user who has both choose which is asked for.
+
+## Recovery codes
+
+`TwoFactor.recoveryCodes(user)` returns the user's codes, making them on first ask; show them once and ask the user to
+keep them somewhere safe. Each works once, in place of a code. `regenerateRecoveryCodes(user)` makes new ones, and the
+old ones stop working.
+
+## Choosing who is asked
+
+By default every user is asked for a second factor once two-factor is on. `requireWhen()` narrows it, for instance to
+admins:
+
+```ts title="app/Providers/AppServiceProvider.ts"
+import { TwoFactor } from '@orieljs/framework'
+import type { User } from '../Models/User'
+// ---cut---
+TwoFactor.requireWhen((user) => (user as User).getAttribute('is_admin') === true)
+```
+
+## Events
+
+`TwoFactorChallenged` (the code was asked for), `TwoFactorFailed` (a wrong code), `TwoFactorAuthenticated` (the user is
+signed in), `RecoveryCodeUsed`, `TwoFactorAppEnabled` and `TwoFactorAppDisabled`, each with the user. The password step
+fires `Attempting` and `Failed`, as `Auth.attempt()` does, and the login fires `Login`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orieljs/framework",
-  "version": "0.1.0-alpha.12",
+  "version": "0.1.0-alpha.13",
   "description": "Oriel: a Laravel-style, full-stack TypeScript framework for Node.js and Bun.",
   "type": "module",
   "license": "Apache-2.0",
@@ -47,6 +47,7 @@
     "@aws-sdk/client-s3": "3.1139.0",
     "@aws-sdk/s3-request-presigner": "3.1139.0",
     "@node-rs/argon2": "2.2.1",
+    "@vercel/blob": "2.8.2",
     "bcryptjs": "3.0.3",
     "better-sqlite3": "13.0.3",
     "cron-parser": "5.10.1",
@@ -55,40 +56,41 @@
     "kysely": "0.29.6",
     "nodemailer": "10.0.10",
     "pino": "10.3.1",
-    "pluralize": "8.0.0"
+    "pluralize": "8.0.0",
+    "uqr": "0.1.3"
   },
   "devDependencies": {
-    "@orieljs/config": "0.1.0-alpha.12",
-    "@orieljs/auth": "0.1.0-alpha.12",
-    "@orieljs/collections": "0.1.0-alpha.12",
-    "@orieljs/bus": "0.1.0-alpha.12",
-    "@orieljs/contracts": "0.1.0-alpha.12",
-    "@orieljs/database": "0.1.0-alpha.12",
-    "@orieljs/cookie": "0.1.0-alpha.12",
-    "@orieljs/encryption": "0.1.0-alpha.12",
-    "@orieljs/container": "0.1.0-alpha.12",
-    "@orieljs/events": "0.1.0-alpha.12",
-    "@orieljs/foundation": "0.1.0-alpha.12",
-    "@orieljs/hashing": "0.1.0-alpha.12",
-    "@orieljs/filesystem": "0.1.0-alpha.12",
-    "@orieljs/http": "0.1.0-alpha.12",
-    "@orieljs/inertia": "0.1.0-alpha.12",
-    "@orieljs/live": "0.1.0-alpha.12",
-    "@orieljs/log": "0.1.0-alpha.12",
-    "@orieljs/mail": "0.1.0-alpha.12",
-    "@orieljs/obfuscate": "0.1.0-alpha.12",
-    "@orieljs/pipeline": "0.1.0-alpha.12",
-    "@orieljs/queue": "0.1.0-alpha.12",
-    "@orieljs/routing": "0.1.0-alpha.12",
-    "@orieljs/cache": "0.1.0-alpha.12",
-    "@orieljs/console": "0.1.0-alpha.12",
-    "@orieljs/notifications": "0.1.0-alpha.12",
-    "@orieljs/support": "0.1.0-alpha.12",
-    "@orieljs/testing": "0.1.0-alpha.12",
-    "@orieljs/validation": "0.1.0-alpha.12",
-    "@orieljs/vercel": "0.1.0-alpha.12",
-    "@orieljs/view": "0.1.0-alpha.12",
-    "@orieljs/session": "0.1.0-alpha.12"
+    "@orieljs/auth": "0.1.0-alpha.13",
+    "@orieljs/bus": "0.1.0-alpha.13",
+    "@orieljs/cache": "0.1.0-alpha.13",
+    "@orieljs/config": "0.1.0-alpha.13",
+    "@orieljs/collections": "0.1.0-alpha.13",
+    "@orieljs/console": "0.1.0-alpha.13",
+    "@orieljs/container": "0.1.0-alpha.13",
+    "@orieljs/database": "0.1.0-alpha.13",
+    "@orieljs/cookie": "0.1.0-alpha.13",
+    "@orieljs/encryption": "0.1.0-alpha.13",
+    "@orieljs/events": "0.1.0-alpha.13",
+    "@orieljs/filesystem": "0.1.0-alpha.13",
+    "@orieljs/hashing": "0.1.0-alpha.13",
+    "@orieljs/http": "0.1.0-alpha.13",
+    "@orieljs/inertia": "0.1.0-alpha.13",
+    "@orieljs/live": "0.1.0-alpha.13",
+    "@orieljs/log": "0.1.0-alpha.13",
+    "@orieljs/mail": "0.1.0-alpha.13",
+    "@orieljs/obfuscate": "0.1.0-alpha.13",
+    "@orieljs/notifications": "0.1.0-alpha.13",
+    "@orieljs/pipeline": "0.1.0-alpha.13",
+    "@orieljs/queue": "0.1.0-alpha.13",
+    "@orieljs/routing": "0.1.0-alpha.13",
+    "@orieljs/session": "0.1.0-alpha.13",
+    "@orieljs/support": "0.1.0-alpha.13",
+    "@orieljs/testing": "0.1.0-alpha.13",
+    "@orieljs/validation": "0.1.0-alpha.13",
+    "@orieljs/vercel": "0.1.0-alpha.13",
+    "@orieljs/view": "0.1.0-alpha.13",
+    "@orieljs/contracts": "0.1.0-alpha.13",
+    "@orieljs/foundation": "0.1.0-alpha.13"
   },
   "peerDependencies": {
     "pg": "^8.23.0",