docs: document registration policy hook and email-change endpoints

Document the OnPreUserRegister hook (Go embedding + JS plugin), the opt-in
built-in RegistrationPolicy with AUTH_REG_* config, and the new
/api/auth/local/email/change and /api/auth/local/email/confirm endpoints.

Claude-Session: https://claude.ai/code/session_014noPgZC7LHPJ376yMNMxH8

Author: ngocphuongnb

src/docs/backend/authentication.md

@@ -162,6 +162,56 @@ Content-Type: application/json
 }
 ```
 
+#### Change Email
+
+Starts an authenticated email change. The request re-authenticates the caller with the current password, validates the new address (format, [registration policy](#registration-policy), and uniqueness), and creates a single-use pending change. It then sends two emails: a notification to the **current** address and a confirmation link to the **new** address. The account email is **not** changed until the new address is confirmed.
+
+Email change is only available for **local (password) accounts**.
+
+**Request:**
+```http
+POST /api/auth/local/email/change HTTP/1.1
+Content-Type: application/json
+Authorization: Bearer <access_token>
+
+{
+  "new_email": "new@example.com",
+  "current_password": "your_current_password"
+}
+```
+
+**Response:**
+```json
+{
+  "message": "A confirmation link has been sent to your new email address"
+}
+```
+
+#### Confirm Email Change
+
+Confirms a pending email change using the single-use, time-limited (24 hours) token delivered to the new address. On success, the account email is committed to the new value.
+
+**Request:**
+```http
+POST /api/auth/local/email/confirm HTTP/1.1
+Content-Type: application/json
+
+{
+  "token": "<token_from_new_email>"
+}
+```
+
+**Response:**
+```json
+{
+  "message": "Your email address has been updated"
+}
+```
+
+::: tip Confirmation link
+The confirmation link base defaults to `<base_url>/auth/local/email/confirm`. To point it at a custom page (for example, a dashboard route that calls the confirm endpoint), set `email_change_url` in the local provider configuration.
+:::
+
 ---
 
 ## Session Management
@@ -278,6 +328,81 @@ Required: `AUTH_OTP_ENABLED=true`
 
 ---
 
+## Registration Policy
+
+FastSchema can apply an opt-in, built-in validation policy to **self-service signups**. The policy runs on **both** local email/password registration and OAuth/social signup, just before the user row is created. It does **not** apply to admin-created users (content API). By default (no policy configured) nothing is blocked.
+
+The policy supports:
+
+| Field | Description |
+|---|---|
+| `allowed_email_domains` | Allowlist. When non-empty, only emails on these domains may register. |
+| `blocked_email_domains` | Denylist of email domains to reject. |
+| `reserved_usernames` | Usernames that may not be registered (e.g. `admin`, `root`, `system`). |
+| `normalize_email` | Lowercases the email domain and converts IDN domains to punycode. |
+
+### Configure via environment variables
+
+Each variable is a comma-separated list. Setting **any** of them enables the policy with `normalize_email` turned on.
+
+| Variable | Description |
+|---|---|
+| `AUTH_REG_ALLOWED_DOMAINS` | Allowed email domains (allowlist). |
+| `AUTH_REG_BLOCKED_DOMAINS` | Blocked email domains (denylist). |
+| `AUTH_REG_RESERVED_USERNAMES` | Reserved usernames. |
+
+```bash
+AUTH_REG_ALLOWED_DOMAINS=example.com,acme.io
+AUTH_REG_RESERVED_USERNAMES=admin,root,system
+```
+
+### Configure programmatically
+
+When embedding FastSchema as a Go framework, set the policy on `AuthConfig`:
+
+```go
+app, _ := fastschema.New(&fs.Config{
+  AuthConfig: &fs.AuthConfig{
+    Registration: &fs.RegistrationPolicy{
+      AllowedEmailDomains: []string{"example.com"},
+      ReservedUsernames:   []string{"admin", "root"},
+      NormalizeEmail:      true,
+    },
+  },
+})
+```
+
+The built-in policy runs as the **first** `OnPreUserRegister` hook, so any custom hooks you register run afterwards on the already-normalized input.
+
+### Custom signup rules (`OnPreUserRegister`)
+
+For anything beyond the basics above — invite-only gating, blocking disposable-email or free-webmail domains, custom username rules — register an `OnPreUserRegister` hook. The hook fires for both local and OAuth signups, may mutate `Email`/`Username` (for example, to normalize them), and returning an error rejects the registration.
+
+```go
+app.OnPreUserRegister(func(ctx context.Context, in *fs.RegistrationInput) error {
+  // Block a disposable-email domain
+  if strings.HasSuffix(strings.ToLower(in.Email), "@tempmail.example") {
+    return errors.BadRequest("Disposable email addresses are not allowed")
+  }
+  return nil
+})
+```
+
+`RegistrationInput` carries the signup data:
+
+| Field | Type | Description |
+|---|---|---|
+| `Email` | `string` | Signup email (mutable). |
+| `Username` | `string` | Signup username (mutable). |
+| `Provider` | `string` | `local` or the OAuth provider name. |
+| `ProviderID` | `string` | OAuth provider subject id (empty for local). |
+| `Profile` | `map[string]any` | Raw provider profile (OAuth only). |
+| `IsOAuth` | `bool` | `true` for social-login registration. |
+
+See the [Hooks](/docs/framework/hooks/#onpreuserregister) reference for more detail, or [Plugin Configuration](/docs/plugins/configuration#add-hooks) to register the hook from a JS plugin.
+
+---
+
 ## Token Usage
 
 Clients must send the access token in every authenticated request. Two methods:
@@ -311,6 +436,9 @@ Cookie: token=<access_token>
 | `AUTH_OTP_LENGTH` | `6` | OTP code length |
 | `AUTH_OTP_EXPIRATION` | `300` | OTP expiration in seconds (5 minutes) |
 | `AUTH_OTP_MAX_ATTEMPTS` | `3` | Max verification attempts before OTP expires |
+| `AUTH_REG_ALLOWED_DOMAINS` | _(empty)_ | Comma-separated allowlist of email domains for signup (see [Registration Policy](#registration-policy)) |
+| `AUTH_REG_BLOCKED_DOMAINS` | _(empty)_ | Comma-separated denylist of email domains for signup |
+| `AUTH_REG_RESERVED_USERNAMES` | _(empty)_ | Comma-separated list of usernames that cannot be registered |
 
 ### Email Templates
 

src/docs/configuration.md

@@ -71,13 +71,27 @@ For the first time you run FastSchema, the application will generate a random `A
 
 ```go
 type AuthConfig struct {
-	EnabledProviders []string       `json:"enabled_providers"`
-	Providers        map[string]Map `json:"providers"`
+	EnabledProviders []string            `json:"enabled_providers"`
+	Providers        map[string]Map      `json:"providers"`
+	Registration     *RegistrationPolicy `json:"registration"` // opt-in signup policy
+}
+
+// RegistrationPolicy is the opt-in built-in validation applied to self-service
+// signup (local + OAuth). All fields are optional; a nil policy blocks nothing.
+type RegistrationPolicy struct {
+	AllowedEmailDomains []string `json:"allowed_email_domains"` // non-empty = allowlist
+	BlockedEmailDomains []string `json:"blocked_email_domains"` // deny list
+	ReservedUsernames   []string `json:"reserved_usernames"`    // admin, root, system, ...
+	NormalizeEmail      bool     `json:"normalize_email"`       // lowercase domain + IDN punycode
 }
 ```
 
 *The `local` provider is enabled by default.*
 
+The optional `registration` policy validates self-service signups for both local and OAuth providers. It can also be configured with the `AUTH_REG_ALLOWED_DOMAINS`, `AUTH_REG_BLOCKED_DOMAINS`, and `AUTH_REG_RESERVED_USERNAMES` environment variables. See [Registration Policy](/docs/backend/authentication#registration-policy) for details.
+
+The `local` provider also accepts an `email_change_url` key, used as the base for the confirmation link sent when a user changes their email address (defaults to `<base_url>/auth/local/email/confirm`). See [Change Email](/docs/backend/authentication#change-email).
+
 For example, to enable the `github` and `google` providers:
 
 ```json
@@ -90,7 +104,8 @@ For example, to enable the `github` and `google` providers:
     "local": {
       "activation_method": "email",
       "activation_url": "http://localhost:3001/activation",
-      "recovery_url": "http://localhost:3001/recover"
+      "recovery_url": "http://localhost:3001/recover",
+      "email_change_url": "http://localhost:3001/email/confirm"
     },
     "github": {
       "client_id": "github_client_id",
@@ -104,6 +119,11 @@ For example, to enable the `github` and `google` providers:
       "consumer_key": "twitter_consumer_key",
       "consumer_secret": "twitter_consumer_secret"
     }
+  },
+  "registration": {
+    "allowed_email_domains": ["example.com"],
+    "reserved_usernames": ["admin", "root", "system"],
+    "normalize_email": true
   }
 }
 ```

src/docs/framework/hooks/index.md

@@ -109,6 +109,63 @@ app.API().Add(fs.Get("hello", func(ctx fs.Context, _ any) (any, error) {
 app.Start()
 ```
 
+## OnPreUserRegister
+
+```go
+type RegistrationInput struct {
+	Email      string         // signup email (mutable)
+	Username   string         // signup username (mutable)
+	Provider   string         // "local" or the OAuth provider name
+	ProviderID string         // OAuth provider subject id (empty for local)
+	Profile    map[string]any // raw provider profile (OAuth only)
+	IsOAuth    bool           // true for social-login registration
+}
+
+type PreUserRegisterHook = func(
+	ctx context.Context,
+	in *RegistrationInput,
+) error
+
+func (a *App) OnPreUserRegister(hooks ...fs.PreUserRegisterHook)
+```
+
+The `OnPreUserRegister` hook is executed just before a **self-service** user is created. It fires for both local (email/password) registration and OAuth/social signup. It does **not** fire for admin-created users.
+
+This is the extension point for custom signup rules such as invite-only gating, or blocking disposable-email / free-webmail domains.
+
+**There are two possible behaviors for the `OnPreUserRegister` hook:**
+
+- `Return nil` to allow the registration to continue.
+- `Return an error` to reject the registration before the user row is created.
+
+The hook receives a pointer to `RegistrationInput` and **may mutate** `Email`/`Username` (for example, to normalize them); the mutated values are applied to the persisted user.
+
+::: tip Built-in registration policy
+The opt-in [Registration Policy](/docs/backend/authentication#registration-policy) (allow/block email domains, reserved usernames, email normalization) runs as the **first** `OnPreUserRegister` hook, so your custom hooks run afterwards on the already-normalized input.
+:::
+
+**Example:**
+
+```go{5-14}
+app, _ := fastschema.New(&fs.Config{
+  SystemSchemas: []any{Tag{}, Blog{}},
+})
+
+app.OnPreUserRegister(func(ctx context.Context, in *fs.RegistrationInput) error {
+  // Invite-only: reject any email that has not been invited
+  if !isInvited(in.Email) {
+    return errors.BadRequest("Registration is invite-only")
+  }
+
+  // Normalize the username
+  in.Username = strings.ToLower(in.Username)
+
+  return nil
+})
+
+app.Start()
+```
+
 ## OnPreDBQuery
 
 ```go{6}

src/docs/plugins/configuration.md

@@ -56,6 +56,8 @@ export interface FsAppConfig {
   OnPreResolve(...hooks: _FsResolveHook[]): void;
   OnPostResolve(...hooks: _FsResolveHook[]): void;
 
+  OnPreUserRegister(...hooks: _FsPreUserRegister[]): void;
+
   OnPreDBQuery(...hooks: _FsPreDBQueryHook[]): void;
   OnPostDBQuery(...hooks: _FsPostDBQueryHook[]): void;
 
@@ -148,6 +150,8 @@ const Config = config => {
   config.OnPreResolve(hookPreResolve);
   config.OnPostResolve(hookPostResolve);
 
+  config.OnPreUserRegister(hookPreUserRegister);
+
   config.OnPreDBQuery(hookPreDBQuery);
   config.OnPostDBQuery(hookPostDBQuery);
 
@@ -170,6 +174,22 @@ const Config = config => {
 ```ts
 export type _FsResolveHook = (ctx: FsContext) => Promise<void> | void;
 
+export interface FsRegistrationInput {
+  email: string;
+  username: string;
+  provider: string;
+  provider_id: string;
+  profile?: { [key: string]: any };
+  is_oauth: boolean;
+}
+
+// Runs before a self-service user is created (local + OAuth).
+// Throw to reject registration. Does NOT fire for admin-created users.
+export type _FsPreUserRegister = (
+  ctx: FsContext,
+  input: FsRegistrationInput,
+) => Promise<void> | void;
+
 export type _FsPreDBQueryHook = (
   ctx: FsContext,
   option: FsQueryOption,
@@ -235,3 +255,22 @@ export type _FsPostDBDeleteHook = (
   affected: number,
 ) => Promise<void> | void;
 ```
+
+## Pre user register hook
+
+The `OnPreUserRegister` hook runs before a self-service user is created, for both local and OAuth signups. Throw to reject the registration; you may also mutate `input.email` / `input.username` (for example, to normalize them). It does **not** fire for admin-created users.
+
+This is the place to implement custom signup rules such as invite-only gating or blocking disposable-email domains. See the [Registration Policy](/docs/backend/authentication#registration-policy) for the built-in basics (allow/block domains, reserved usernames, email normalization).
+
+```js [plugin.js]
+const hookPreUserRegister = (ctx, input) => {
+  // Block a disposable-email domain
+  if (input.email.toLowerCase().endsWith('@tempmail.example')) {
+    throw new Error('Disposable email addresses are not allowed');
+  }
+};
+
+const Config = config => {
+  config.OnPreUserRegister(hookPreUserRegister);
+}
+```