@netlify/identity 1.0.0 → 1.2.0

package/README.md

@@ -1,17 +1,27 @@
 # @netlify/identity
 
-A lightweight, no-config headless authentication library for projects using Netlify Identity. Works in both browser and server contexts.
-This is NOT the Netlify Identity Widget. This library exports standalone async functions (e.g., import { login, getUser } from '@netlify/identity'). There is no class to instantiate and no .init() call. Just import the functions you need and call them.
+A lightweight, no-config headless authentication library for projects using Netlify Identity. Works in both browser and
+server contexts. This is NOT the Netlify Identity Widget. This library exports standalone async functions (e.g., import
+{ login, getUser } from '@netlify/identity'). There is no class to instantiate and no .init() call. Just import the
+functions you need and call them.
 
 **Prerequisites:**
 
-- [Netlify Identity](https://docs.netlify.com/security/secure-access-to-sites/identity/) must be enabled on your Netlify project. This happens automatically when running within a [Netlify Agent Runner](https://docs.netlify.com/agent-runner/overview/)
-- **Server-side** functions (`getUser`, `login`, `admin.*`, etc.) require [Netlify Functions](https://docs.netlify.com/build/functions/get-started/) (modern/v2, with `export default`) or [Edge Functions](https://docs.netlify.com/edge-functions/overview/). [Lambda-compatible functions](https://docs.netlify.com/build/functions/lambda-compatibility/) (v1, with `export { handler }`) are **not supported**
-- For local development, use [`netlify dev`](https://docs.netlify.com/cli/local-development/) so the Identity endpoint is available
+- [Netlify Identity](https://docs.netlify.com/security/secure-access-to-sites/identity/) must be enabled on your Netlify
+  project. This happens automatically when running within a
+  [Netlify Agent Runner](https://docs.netlify.com/agent-runner/overview/)
+- **Server-side** functions (`getUser`, `login`, `admin.*`, etc.) require
+  [Netlify Functions](https://docs.netlify.com/build/functions/get-started/) (modern/v2, with `export default`) or
+  [Edge Functions](https://docs.netlify.com/edge-functions/overview/).
+  [Lambda-compatible functions](https://docs.netlify.com/build/functions/lambda-compatibility/) (v1, with
+  `export { handler }`) are **not supported**
+- For local development, use [`netlify dev`](https://docs.netlify.com/cli/local-development/) so the Identity endpoint
+  is available
 
 ## How this library relates to other Netlify auth packages
 
-`@netlify/identity` is the recommended library for all new projects. It works in both browser and server contexts, handles cookie management, and normalizes the user object.
+`@netlify/identity` is the recommended library for all new projects. It works in both browser and server contexts,
+handles cookie management, and normalizes the user object.
 
 You may encounter two older packages in existing code or documentation:
 
@@ -20,17 +30,22 @@ You may encounter two older packages in existing code or documentation:
 | [`netlify-identity-widget`](https://github.com/netlify/netlify-identity-widget) | Not recommended for new projects | Pre-built login/signup modal with built-in UI |
 | [`gotrue-js`](https://github.com/netlify/gotrue-js)                             | Not recommended for new projects | Low-level GoTrue HTTP client (browser only)   |
 
-If you need a pre-built login UI, the widget still works. For everything else (custom UI, server-side auth, admin operations, framework integration), use `@netlify/identity`.
+If you need a pre-built login UI, the widget still works. For everything else (custom UI, server-side auth, admin
+operations, framework integration), use `@netlify/identity`.
 
 ## Table of contents
 
 - [Installation](#installation)
 - [Quick start](#quick-start)
 - [API](#api)
-  - [Functions](#functions) -- `getUser`, `login`, `signup`, `logout`, `oauthLogin`, `handleAuthCallback`, `onAuthChange`, `hydrateSession`, `refreshSession`, and more
-  - [Admin Operations](#admin-operations) -- `admin.listUsers`, `admin.getUser`, `admin.createUser`, `admin.updateUser`, `admin.deleteUser`
-  - [Types](#types) -- `User`, `AuthEvent`, `CallbackResult`, `Settings`, `Admin`, `ListUsersOptions`, `CreateUserParams`, etc.
+  - [Functions](#functions) -- `getUser`, `login`, `signup`, `logout`, `oauthLogin`, `handleAuthCallback`,
+    `onAuthChange`, `hydrateSession`, `refreshSession`, `verifyRequestOrigin`, and more
+  - [Admin Operations](#admin-operations) -- `admin.listUsers`, `admin.getUser`, `admin.createUser`, `admin.updateUser`,
+    `admin.deleteUser`
+  - [Types](#types) -- `User`, `AuthEvent`, `CallbackResult`, `Settings`, `Admin`, `ListUsersOptions`,
+    `CreateUserParams`, `VerifyRequestOriginOptions`, etc.
   - [Errors](#errors) -- `AuthError`, `MissingIdentityError`
+- [Security: CSRF protection](#security-csrf-protection)
 - [Framework integration](#framework-integration) -- Next.js, Remix, TanStack Start, Astro, SvelteKit
 - [Guides](#guides)
   - [React `useAuth` hook](#react-useauth-hook)
@@ -98,9 +113,16 @@ export default async (req: Request, context: Context) => {
 getUser(): Promise<User | null>
 ```
 
-Returns the current authenticated user, or `null` if not logged in. Returns the best available normalized `User` from the current context. When the Identity API is reachable, most persisted and profile fields are populated, but state-dependent fields (invite, recovery, email-change) may still be `undefined` if the user is not in that state. When falling back to JWT claims (e.g., Identity API unreachable), only `id`, `email`, `provider`, `name`, `pictureUrl`, `roles`, `userMetadata`, and `appMetadata` are available. Never throws.
+Returns the current authenticated user, or `null` if not logged in. Returns the best available normalized `User` from
+the current context. When the Identity API is reachable, most persisted and profile fields are populated, but
+state-dependent fields (invite, recovery, email-change) may still be `undefined` if the user is not in that state. When
+falling back to JWT claims (e.g., Identity API unreachable), only `id`, `email`, `provider`, `name`, `pictureUrl`,
+`roles`, `userMetadata`, and `appMetadata` are available. Never throws.
 
-> **Next.js note:** Calling `getUser()` in a Server Component opts the page into [dynamic rendering](https://nextjs.org/docs/app/building-your-application/rendering/server-components#dynamic-rendering) because it reads cookies. This is expected and correct for authenticated pages. Next.js handles the internal dynamic rendering signal automatically.
+> **Next.js note:** Calling `getUser()` in a Server Component opts the page into
+> [dynamic rendering](https://nextjs.org/docs/app/building-your-application/rendering/server-components#dynamic-rendering)
+> because it reads cookies. This is expected and correct for authenticated pages. Next.js handles the internal dynamic
+> rendering signal automatically.
 
 #### `isAuthenticated`
 
@@ -116,7 +138,8 @@ Returns `true` if a user is currently authenticated. Equivalent to `(await getUs
 getIdentityConfig(): IdentityConfig | null
 ```
 
-Returns the Identity endpoint URL (and operator token on the server), or `null` if Identity is not available. Never throws.
+Returns the Identity endpoint URL (and operator token on the server), or `null` if Identity is not available. Never
+throws.
 
 #### `getSettings`
 
@@ -136,9 +159,11 @@ login(email: string, password: string): Promise<User>
 
 Logs in with email and password. Works in both browser and server contexts.
 
-In the browser, emits a `'login'` event. On the server (Netlify Functions, Edge Functions), calls the Identity API directly and sets the `nf_jwt` cookie via the Netlify runtime.
+In the browser, emits a `'login'` event. On the server (Netlify Functions, Edge Functions), calls the Identity API
+directly and sets the `nf_jwt` cookie via the Netlify runtime.
 
-**Throws:** `AuthError` on invalid credentials or network failure. In the browser, `MissingIdentityError` if Identity is not configured. On the server, `AuthError` if the Netlify Functions runtime is not available.
+**Throws:** `AuthError` on invalid credentials or network failure. In the browser, `MissingIdentityError` if Identity is
+not configured. On the server, `AuthError` if the Netlify Functions runtime is not available.
 
 #### `signup`
 
@@ -148,11 +173,16 @@ signup(email: string, password: string, data?: SignupData): Promise<User>
 
 Creates a new account. Works in both browser and server contexts.
 
-If autoconfirm is enabled in your Identity settings, the user is logged in immediately: cookies are set and a `'login'` event is emitted. If autoconfirm is **disabled** (the default), the user receives a confirmation email and must click the link before they can log in. In that case, no cookies are set and no auth event is emitted.
+If autoconfirm is enabled in your Identity settings, the user is logged in immediately: cookies are set and a `'login'`
+event is emitted. If autoconfirm is **disabled** (the default), the user receives a confirmation email and must click
+the link before they can log in. In that case, no cookies are set and no auth event is emitted.
 
-The optional `data` parameter sets user metadata (e.g., `{ full_name: 'Jane Doe' }`), stored in the user's `user_metadata` field.
+The optional `data` parameter sets user metadata (e.g., `{ full_name: 'Jane Doe' }`), stored in the user's
+`user_metadata` field.
 
-**Throws:** `AuthError` on failure (e.g., email already registered, signup disabled). In the browser, `MissingIdentityError` if Identity is not configured. On the server, `AuthError` if the Netlify Functions runtime is not available.
+**Throws:** `AuthError` on failure (e.g., email already registered, signup disabled). In the browser,
+`MissingIdentityError` if Identity is not configured. On the server, `AuthError` if the Netlify Functions runtime is not
+available.
 
 #### `logout`
 
@@ -162,9 +192,11 @@ logout(): Promise<void>
 
 Logs out the current user and clears the session. Works in both browser and server contexts.
 
-In the browser, emits a `'logout'` event. On the server, calls the Identity `/logout` endpoint with the JWT from the `nf_jwt` cookie, then deletes the cookie. Auth cookies are always cleared, even if the server call fails.
+In the browser, emits a `'logout'` event. On the server, calls the Identity `/logout` endpoint with the JWT from the
+`nf_jwt` cookie, then deletes the cookie. Auth cookies are always cleared, even if the server call fails.
 
-**Throws:** In the browser, `MissingIdentityError` if Identity is not configured. On the server, `AuthError` if the Netlify Functions runtime is not available.
+**Throws:** In the browser, `MissingIdentityError` if Identity is not configured. On the server, `AuthError` if the
+Netlify Functions runtime is not available.
 
 #### `oauthLogin`
 
@@ -174,7 +206,8 @@ oauthLogin(provider: string): never
 
 Redirects to an OAuth provider. The page navigates away, so this function never returns normally. Browser only.
 
-The `provider` argument should be one of the `AuthProvider` values: `'google'`, `'github'`, `'gitlab'`, `'bitbucket'`, or `'facebook'`.
+The `provider` argument should be one of the `AuthProvider` values: `'google'`, `'github'`, `'gitlab'`, `'bitbucket'`,
+or `'facebook'`.
 
 **Throws:** `MissingIdentityError` if Identity is not configured. `AuthError` if called on the server.
 
@@ -184,7 +217,8 @@ The `provider` argument should be one of the `AuthProvider` values: `'google'`,
 handleAuthCallback(): Promise<CallbackResult | null>
 ```
 
-Processes the URL hash after an OAuth redirect, email confirmation, password recovery, invite acceptance, or email change. Call on page load. Returns `null` if the hash contains no auth parameters. Browser only.
+Processes the URL hash after an OAuth redirect, email confirmation, password recovery, invite acceptance, or email
+change. Call on page load. Returns `null` if the hash contains no auth parameters. Browser only.
 
 **Throws:** `MissingIdentityError` if Identity is not configured. `AuthError` if token exchange fails.
 
@@ -194,7 +228,9 @@ Processes the URL hash after an OAuth redirect, email confirmation, password rec
 onAuthChange(callback: AuthCallback): () => void
 ```
 
-Subscribes to auth state changes (login, logout, token refresh, user updates, and recovery). Returns an unsubscribe function. Also fires on cross-tab session changes. No-op on the server. The `'recovery'` event fires when `handleAuthCallback()` processes a password recovery token; listen for it to redirect users to a password reset form.
+Subscribes to auth state changes (login, logout, token refresh, user updates, and recovery). Returns an unsubscribe
+function. Also fires on cross-tab session changes. No-op on the server. The `'recovery'` event fires when
+`handleAuthCallback()` processes a password recovery token; listen for it to redirect users to a password reset form.
 
 #### `hydrateSession`
 
@@ -202,9 +238,13 @@ Subscribes to auth state changes (login, logout, token refresh, user updates, an
 hydrateSession(): Promise<User | null>
 ```
 
-Bootstraps the browser-side session from server-set auth cookies (`nf_jwt`, `nf_refresh`). Returns the hydrated `User`, or `null` if no auth cookies are present. No-op on the server.
+Bootstraps the browser-side session from server-set auth cookies (`nf_jwt`, `nf_refresh`). Returns the hydrated `User`,
+or `null` if no auth cookies are present. No-op on the server.
 
-**When to use:** After a server-side login (e.g., via a Netlify Function or Server Action), the `nf_jwt` cookie is set but no browser session exists yet. `getUser()` calls `hydrateSession()` automatically, but account operations like `updateUser()` or `verifyEmailChange()` require a live browser session. Call `hydrateSession()` explicitly if you need the session ready before calling those operations.
+**When to use:** After a server-side login (e.g., via a Netlify Function or Server Action), the `nf_jwt` cookie is set
+but no browser session exists yet. `getUser()` calls `hydrateSession()` automatically, but account operations like
+`updateUser()` or `verifyEmailChange()` require a live browser session. Call `hydrateSession()` explicitly if you need
+the session ready before calling those operations.
 
 If a browser session already exists (e.g., from a browser-side login), this is a no-op and returns the existing user.
 
@@ -224,13 +264,22 @@ await updateUser({ data: { full_name: 'Jane Doe' } })
 refreshSession(): Promise<string | null>
 ```
 
-Refreshes an expired or near-expired session. Returns the new access token on success, or `null` if no refresh is needed or the refresh token is invalid/missing.
+Refreshes an expired or near-expired session. Returns the new access token on success, or `null` if no refresh is needed
+or the refresh token is invalid/missing.
 
-**Browser:** Checks if the current access token is near expiry and refreshes it if needed, syncing the new token to the `nf_jwt` cookie. Note: the library automatically refreshes tokens in the background after any browser flow that establishes a session (`login()`, `signup()`, `hydrateSession()`, `handleAuthCallback()`, `confirmEmail()`, `recoverPassword()`, `acceptInvite()`), so you typically don't need to call this manually. `getUser()` also restarts the refresh timer when it finds an existing session. Browser-side errors return `null`, not an `AuthError`.
+**Browser:** Checks if the current access token is near expiry and refreshes it if needed, syncing the new token to the
+`nf_jwt` cookie. Note: the library automatically refreshes tokens in the background after any browser flow that
+establishes a session (`login()`, `signup()`, `hydrateSession()`, `handleAuthCallback()`, `confirmEmail()`,
+`recoverPassword()`, `acceptInvite()`), so you typically don't need to call this manually. `getUser()` also restarts the
+refresh timer when it finds an existing session. Browser-side errors return `null`, not an `AuthError`.
 
-**Server:** Reads the `nf_jwt` and `nf_refresh` cookies. If the access token is expired or within 60 seconds of expiry, exchanges the refresh token for a new access token via the Identity `/token` endpoint and updates both cookies on the response. Call this in framework middleware or at the start of server-side request handlers to ensure the JWT is valid for downstream processing.
+**Server:** Reads the `nf_jwt` and `nf_refresh` cookies. If the access token is expired or within 60 seconds of expiry,
+exchanges the refresh token for a new access token via the Identity `/token` endpoint and updates both cookies on the
+response. Call this in framework middleware or at the start of server-side request handlers to ensure the JWT is valid
+for downstream processing.
 
-**Throws:** `AuthError` on network failure or if the Identity endpoint URL cannot be determined. Does **not** throw for invalid/expired refresh tokens (returns `null` instead).
+**Throws:** `AuthError` on network failure or if the Identity endpoint URL cannot be determined. Does **not** throw for
+invalid/expired refresh tokens (returns `null` instead).
 
 ```ts
 // Example: Astro middleware
@@ -242,6 +291,24 @@ export async function onRequest(context, next) {
 }
 ```
 
+#### `verifyRequestOrigin`
+
+```ts
+verifyRequestOrigin(request: Request, options?: VerifyRequestOriginOptions): void
+```
+
+CSRF protection helper for server-side endpoints that call `login()`, `signup()`, or `logout()`. Compares the request's
+`Origin` header against the request's own origin (or an explicit allowlist via `options.allowedOrigins`) and throws if
+they don't match. Server-only.
+
+The check runs unconditionally on every call: any HTTP method, with or without an `Origin` header. If you don't want the
+check on a particular route, don't call the helper there.
+
+**Throws:** `AuthError` with status `403` when the request has no `Origin` header. `AuthError` with status `403` when
+the request's `Origin` is not in the allowed origins.
+
+See [Security: CSRF protection](#security-csrf-protection) for the full threat model and per-framework guidance.
+
 #### `requestPasswordRecovery`
 
 ```ts
@@ -298,13 +365,16 @@ Redeems a recovery token and sets a new password. Logs the user in on success.
 updateUser(updates: UserUpdates): Promise<User>
 ```
 
-Updates the current user's metadata or credentials. Requires an active session. Pass `email` or `password` to change credentials, or `data` to update user metadata (e.g., `{ data: { full_name: 'New Name' } }`).
+Updates the current user's metadata or credentials. Requires an active session. Pass `email` or `password` to change
+credentials, or `data` to update user metadata (e.g., `{ data: { full_name: 'New Name' } }`).
 
-**Throws:** `MissingIdentityError` if Identity is not configured. `AuthError` if no user is logged in, or the update fails.
+**Throws:** `MissingIdentityError` if Identity is not configured. `AuthError` if no user is logged in, or the update
+fails.
 
 ### Admin Operations
 
-The `admin` namespace provides server-only user management functions. Admin methods use the operator token from the Netlify runtime, which is automatically available in Netlify Functions and Edge Functions.
+The `admin` namespace provides server-only user management functions. Admin methods use the operator token from the
+Netlify runtime, which is automatically available in Netlify Functions and Edge Functions.
 
 Calling any admin method from a browser environment throws an `AuthError`.
 
@@ -362,7 +432,9 @@ Gets a single user by ID.
 admin.createUser(params: CreateUserParams): Promise<User>
 ```
 
-Creates a new user. The user is auto-confirmed. Optional `data` forwards allowed fields (`role`, `app_metadata`, `user_metadata`) to the request body. Other keys are silently ignored. `data` cannot override `email`, `password`, or `confirm`.
+Creates a new user. The user is auto-confirmed. Optional `data` forwards allowed fields (`role`, `app_metadata`,
+`user_metadata`) to the request body. Other keys are silently ignored. `data` cannot override `email`, `password`, or
+`confirm`.
 
 **Throws:** `AuthError` if called from a browser, the email already exists, or the operator token is missing.
 
@@ -372,7 +444,8 @@ Creates a new user. The user is auto-confirmed. Optional `data` forwards allowed
 admin.updateUser(userId: string, attributes: AdminUserUpdates): Promise<User>
 ```
 
-Updates an existing user by ID. Only typed `AdminUserUpdates` fields are forwarded (e.g., `{ email: 'new@example.com' }`, `{ role: 'editor' }`).
+Updates an existing user by ID. Only typed `AdminUserUpdates` fields are forwarded (e.g.,
+`{ email: 'new@example.com' }`, `{ role: 'editor' }`).
 
 **Throws:** `AuthError` if called from a browser, the user is not found, or the update fails.
 
@@ -464,7 +537,8 @@ interface AdminUserUpdates {
 }
 ```
 
-Fields accepted by `admin.updateUser()`. Unlike `UserUpdates`, admin updates can set `role`, force-confirm a user, and write to `app_metadata`. Only these typed fields are forwarded.
+Fields accepted by `admin.updateUser()`. Unlike `UserUpdates`, admin updates can set `role`, force-confirm a user, and
+write to `app_metadata`. Only these typed fields are forwarded.
 
 #### `SignupData`
 
@@ -505,7 +579,8 @@ interface CreateUserParams {
 }
 ```
 
-Parameters for `admin.createUser()`. Optional `data` forwards allowed fields (`role`, `app_metadata`, `user_metadata`) to the request body. Other keys are silently ignored.
+Parameters for `admin.createUser()`. Optional `data` forwards allowed fields (`role`, `app_metadata`, `user_metadata`)
+to the request body. Other keys are silently ignored.
 
 #### `Admin`
 
@@ -565,9 +640,23 @@ interface CallbackResult {
 }
 ```
 
-The `token` field is only present for `invite` callbacks, where the user hasn't set a password yet. Pass `token` to `acceptInvite(token, password)` to finish.
+The `token` field is only present for `invite` callbacks, where the user hasn't set a password yet. Pass `token` to
+`acceptInvite(token, password)` to finish.
+
+For all other types (`oauth`, `confirmation`, `recovery`, `email_change`), the user is logged in directly and `token` is
+not set.
+
+#### `VerifyRequestOriginOptions`
 
-For all other types (`oauth`, `confirmation`, `recovery`, `email_change`), the user is logged in directly and `token` is not set.
+```ts
+interface VerifyRequestOriginOptions {
+  allowedOrigins?: string[]
+}
+```
+
+Options for [`verifyRequestOrigin`](#verifyrequestorigin). When `allowedOrigins` is set, the list replaces the default
+same-origin check, so include the request's own origin if you still want it allowed. Each value is a full origin string
+with scheme and host (`'https://example.com'`).
 
 ### Errors
 
@@ -588,6 +677,59 @@ class MissingIdentityError extends Error {}
 
 Thrown when Identity is not configured in the current environment.
 
+## Security: CSRF protection
+
+If you expose server-side `login()`, `signup()`, or `logout()` through an HTTP endpoint, that endpoint needs Cross-Site
+Request Forgery (CSRF) protection. The library cannot enforce this itself because it only sees the email and password
+arguments handed to it, not the incoming request.
+
+**Why it matters.** A specific flavor called _login CSRF_ lets an attacker trick a victim's browser into logging into
+the attacker's account. The victim then performs actions inside that session (saving payment info, linking third-party
+services, uploading content), and the attacker harvests the result later by signing in with the credentials they always
+controlled. `SameSite=Lax` cookies do not catch this attack because the session is being created on the victim's
+browser, not ridden from an existing one.
+
+### `verifyRequestOrigin`
+
+`verifyRequestOrigin(request, options?)` compares the request's `Origin` header against the request's own origin (or an
+explicit allowlist) and throws `AuthError` with status 403 on mismatch. Call it at the start of any handler that
+performs an auth mutation.
+
+```ts
+// netlify/functions/login.ts
+import { login, verifyRequestOrigin } from '@netlify/identity'
+import type { Context } from '@netlify/functions'
+
+export default async (req: Request, context: Context) => {
+  verifyRequestOrigin(req)
+  const { email, password } = await req.json()
+  await login(email, password)
+  return new Response(null, { status: 302, headers: { Location: '/dashboard' } })
+}
+```
+
+The helper runs unconditionally on every call. It checks any HTTP method, with or without an `Origin` header. If you
+don't want the check on a particular route, don't call the helper there.
+
+### Custom allowed origins
+
+By default, the helper accepts only the request's own origin. Pass `allowedOrigins` to allow additional trusted origins
+(for example, a separate frontend domain that POSTs to an API on another domain). The list replaces the default, so
+include the request's own origin if you still want it allowed:
+
+```ts
+verifyRequestOrigin(req, {
+  allowedOrigins: ['https://app.example.com', 'https://www.example.com'],
+})
+```
+
+### When to call the helper
+
+Some frameworks check the request's `Origin` on state-changing requests by default; others don't. Check your framework's
+documentation. If same-origin enforcement is already on by default for the endpoint where you invoke `login()` /
+`signup()` / `logout()`, calling `verifyRequestOrigin` yourself is redundant. If it isn't, call
+`verifyRequestOrigin(request)` at the start of the handler before invoking the auth function.
+
 ## Framework integration
 
 ### Recommended pattern for SSR frameworks
@@ -597,9 +739,13 @@ For SSR frameworks (Next.js, Remix, Astro, TanStack Start), the recommended patt
 - **Browser-side** for auth mutations: `login()`, `signup()`, `logout()`, `oauthLogin()`
 - **Server-side** for reading auth state: `getUser()`, `getSettings()`, `getIdentityConfig()`
 
-Browser-side auth mutations call the Identity API directly from the browser, set the `nf_jwt` cookie, and emit `onAuthChange` events. This keeps the client UI in sync immediately. Server-side reads work because the cookie is sent with every request.
+Browser-side auth mutations call the Identity API directly from the browser, set the `nf_jwt` cookie, and emit
+`onAuthChange` events. This keeps the client UI in sync immediately. Server-side reads work because the cookie is sent
+with every request.
 
-The library also supports server-side mutations (`login()`, `signup()`, `logout()` inside Netlify Functions), but these require the Netlify Functions runtime to set cookies. After a server-side mutation, you need a full page navigation so the browser sends the new cookie.
+The library also supports server-side mutations (`login()`, `signup()`, `logout()` inside Netlify Functions), but these
+require the Netlify Functions runtime to set cookies. After a server-side mutation, you need a full page navigation so
+the browser sends the new cookie.
 
 ### Next.js (App Router)
 
@@ -653,7 +799,10 @@ export default async function Dashboard() {
 }
 ```
 
-Use `window.location.href` instead of Next.js `redirect()` after server-side auth mutations. Next.js `redirect()` triggers a soft navigation via the Router, which may not include the newly-set auth cookie. A full page load ensures the cookie is sent and the server sees the updated auth state. Reading auth state with `getUser()` in Server Components works normally, and `redirect()` is fine for auth gates (where no cookie was just set).
+Use `window.location.href` instead of Next.js `redirect()` after server-side auth mutations. Next.js `redirect()`
+triggers a soft navigation via the Router, which may not include the newly-set auth cookie. A full page load ensures the
+cookie is sent and the server sees the updated auth state. Reading auth state with `getUser()` in Server Components
+works normally, and `redirect()` is fine for auth gates (where no cookie was just set).
 
 ### Remix
 
@@ -661,11 +810,12 @@ Use `window.location.href` instead of Next.js `redirect()` after server-side aut
 
 ```tsx
 // app/routes/login.tsx
-import { login } from '@netlify/identity'
+import { login, verifyRequestOrigin } from '@netlify/identity'
 import { redirect, json } from '@remix-run/node'
 import type { ActionFunctionArgs } from '@remix-run/node'
 
 export async function action({ request }: ActionFunctionArgs) {
+  verifyRequestOrigin(request)
   const formData = await request.formData()
   const email = formData.get('email') as string
   const password = formData.get('password') as string
@@ -691,7 +841,13 @@ export async function loader() {
 }
 ```
 
-Remix `redirect()` works after server-side `login()` because Remix actions return real HTTP responses. The browser receives a 302 with the `Set-Cookie` header already applied, so the next request includes the auth cookie. This is different from Next.js, where `redirect()` in a Server Action triggers a client-side (soft) navigation that may not include newly-set cookies.
+Remix `redirect()` works after server-side `login()` because Remix actions return real HTTP responses. The browser
+receives a 302 with the `Set-Cookie` header already applied, so the next request includes the auth cookie. This is
+different from Next.js, where `redirect()` in a Server Action triggers a client-side (soft) navigation that may not
+include newly-set cookies.
+
+> The example calls [`verifyRequestOrigin`](#verifyrequestorigin) at the top of the action. See
+> [Security: CSRF protection](#security-csrf-protection) for when this is needed.
 
 ### TanStack Start
 
@@ -758,7 +914,8 @@ function Dashboard() {
 }
 ```
 
-Use `window.location.href` instead of TanStack Router's `navigate()` after auth changes. This ensures the browser sends the updated cookie on the next request.
+Use `window.location.href` instead of TanStack Router's `navigate()` after auth changes. This ensures the browser sends
+the updated cookie on the next request.
 
 ### Astro (SSR)
 
@@ -840,7 +997,9 @@ export async function load() {
 
 ### Handling OAuth callbacks in SPAs
 
-All SPA frameworks need a callback handler that runs on page load to process OAuth redirects, email confirmations, and password recovery tokens. Use a **wrapper component** that blocks page content while processing tokens. This prevents a flash of unauthenticated content that occurs when the page renders before the callback completes.
+All SPA frameworks need a callback handler that runs on page load to process OAuth redirects, email confirmations, and
+password recovery tokens. Use a **wrapper component** that blocks page content while processing tokens. This prevents a
+flash of unauthenticated content that occurs when the page renders before the callback completes.
 
 ```tsx
 // React component (works with Next.js, Remix, TanStack Start)
@@ -893,7 +1052,8 @@ Wrap your page content with this component in your **root layout** so it runs on
 </CallbackHandler>
 ```
 
-If you only mount it on a `/callback` route, OAuth redirects and email confirmation links that land on other pages will not be processed.
+If you only mount it on a `/callback` route, OAuth redirects and email confirmation links that land on other pages will
+not be processed.
 
 ## Guides
 
@@ -927,7 +1087,8 @@ function NavBar() {
 
 ### Listening for auth changes
 
-Use `onAuthChange` to keep your UI in sync with auth state. It fires on login, logout, token refresh, user updates, and recovery. It also detects session changes in other browser tabs (via `localStorage`).
+Use `onAuthChange` to keep your UI in sync with auth state. It fires on login, logout, token refresh, user updates, and
+recovery. It also detects session changes in other browser tabs (via `localStorage`).
 
 ```ts
 import { onAuthChange, AUTH_EVENTS } from '@netlify/identity'
@@ -982,11 +1143,15 @@ if (result?.type === 'oauth') {
 }
 ```
 
-`handleAuthCallback()` exchanges the token in the URL hash, logs the user in, clears the hash, and emits an auth event via `onAuthChange` (`'login'` for OAuth/confirmation, `'recovery'` for password recovery).
+`handleAuthCallback()` exchanges the token in the URL hash, logs the user in, clears the hash, and emits an auth event
+via `onAuthChange` (`'login'` for OAuth/confirmation, `'recovery'` for password recovery).
 
 ### Password recovery
 
-Password recovery is a two-step flow. The library handles the token exchange automatically via `handleAuthCallback()`, which logs the user in and returns `{type: 'recovery', user}`. A `'recovery'` event (not `'login'`) is emitted via `onAuthChange`, so event-based listeners can also detect this flow. You then show a "set new password" form and call `updateUser()` to save it.
+Password recovery is a two-step flow. The library handles the token exchange automatically via `handleAuthCallback()`,
+which logs the user in and returns `{type: 'recovery', user}`. A `'recovery'` event (not `'login'`) is emitted via
+`onAuthChange`, so event-based listeners can also detect this flow. You then show a "set new password" form and call
+`updateUser()` to save it.
 
 **Step by step:**
 
@@ -1022,7 +1187,9 @@ onAuthChange((event, user) => {
 
 ### Invite acceptance
 
-When an admin invites a user, they receive an email with an invite link. Clicking it redirects to your site with an `invite_token` in the URL hash. Unlike other callback types, the user is not logged in automatically because they need to set a password first.
+When an admin invites a user, they receive an email with an invite link. Clicking it redirects to your site with an
+`invite_token` in the URL hash. Unlike other callback types, the user is not logged in automatically because they need
+to set a password first.
 
 **Step by step:**
 
@@ -1048,25 +1215,46 @@ Sessions are managed by Netlify Identity on the server side. The library stores
 - **`nf_jwt`**: A short-lived JWT access token (default: 1 hour).
 - **`nf_refresh`**: A long-lived refresh token used to obtain new access tokens without re-authenticating.
 
-**Browser auto-refresh:** After any session-establishing flow (`login()`, `signup()`, `hydrateSession()`, `handleAuthCallback()`, `confirmEmail()`, `recoverPassword()`, `acceptInvite()`), the library automatically schedules a background refresh 60 seconds before the access token expires. `getUser()` also restarts the refresh timer when it finds an existing session (e.g., after a page reload). When the refresh fires, it obtains a new access token, syncs it to the `nf_jwt` cookie, and emits a `TOKEN_REFRESH` event. This keeps the cookie fresh as long as the user has the tab open. If the refresh fails (e.g., the refresh token was revoked), the timer stops and the user will need to log in again.
+**Browser auto-refresh:** After any session-establishing flow (`login()`, `signup()`, `hydrateSession()`,
+`handleAuthCallback()`, `confirmEmail()`, `recoverPassword()`, `acceptInvite()`), the library automatically schedules a
+background refresh 60 seconds before the access token expires. `getUser()` also restarts the refresh timer when it finds
+an existing session (e.g., after a page reload). When the refresh fires, it obtains a new access token, syncs it to the
+`nf_jwt` cookie, and emits a `TOKEN_REFRESH` event. This keeps the cookie fresh as long as the user has the tab open. If
+the refresh fails (e.g., the refresh token was revoked), the timer stops and the user will need to log in again.
 
-**Server-side refresh:** On the server, the access token in the `nf_jwt` cookie is validated as-is. If it has expired and no refresh happens, `getUser()` returns `null`. To handle this, call `refreshSession()` in your framework middleware or request handler. This checks if the token is near expiry, exchanges the refresh token for a new one, and updates the cookies on the response.
+**Server-side refresh:** On the server, the access token in the `nf_jwt` cookie is validated as-is. If it has expired
+and no refresh happens, `getUser()` returns `null`. To handle this, call `refreshSession()` in your framework middleware
+or request handler. This checks if the token is near expiry, exchanges the refresh token for a new one, and updates the
+cookies on the response.
 
 Session lifetime is configured in your Netlify Identity settings, not in this library.
 
 ### Caching and authenticated content
 
-Pages that display user-specific data (names, emails, roles, account settings) should not be served from a shared cache. If a cache stores an authenticated response and serves it to a different user, that user sees someone else's data. This applies to any authentication system, not just Netlify Identity.
+Pages that display user-specific data (names, emails, roles, account settings) should not be served from a shared cache.
+If a cache stores an authenticated response and serves it to a different user, that user sees someone else's data. This
+applies to any authentication system, not just Netlify Identity.
 
 **Next.js App Router** has multiple caching layers that are active by default:
 
-- **Static rendering:** Server Components are statically rendered at build time unless they call a [Dynamic API](https://nextjs.org/docs/app/guides/caching#dynamic-rendering) like `cookies()`. This library's `getUser()` already calls `headers()` internally to opt the route into dynamic rendering, but if you check auth state without calling `getUser()` (e.g., reading the `nf_jwt` cookie directly), the page may still be statically cached. Always use `getUser()` rather than reading cookies directly.
-- **ISR (Incremental Static Regeneration):** Do not use ISR for pages that display user-specific content. ISR regenerates the page for the first visitor after the revalidation window and caches the result for all subsequent visitors.
-- **`use cache` / `unstable_cache`:** These directives cannot access `cookies()` or `headers()` directly. If you need to cache part of an authenticated page, read cookies outside the cache scope and pass relevant values as arguments.
-
-> **Note:** Next.js caching defaults have changed across versions. For example, [Next.js 15 changed `fetch` requests, `GET` Route Handlers, and the client Router Cache to be uncached by default](https://nextjs.org/blog/next-15#caching-semantics), reversing the previous opt-out model. Check the [caching guide](https://nextjs.org/docs/app/guides/caching) for your specific Next.js version.
-
-**Other SSR frameworks (Remix, Astro, SvelteKit, TanStack Start):** These frameworks do not cache SSR responses by default. If you add caching headers to improve performance, exclude routes that call `getUser()` or read auth cookies.
+- **Static rendering:** Server Components are statically rendered at build time unless they call a
+  [Dynamic API](https://nextjs.org/docs/app/guides/caching#dynamic-rendering) like `cookies()`. This library's
+  `getUser()` already calls `headers()` internally to opt the route into dynamic rendering, but if you check auth state
+  without calling `getUser()` (e.g., reading the `nf_jwt` cookie directly), the page may still be statically cached.
+  Always use `getUser()` rather than reading cookies directly.
+- **ISR (Incremental Static Regeneration):** Do not use ISR for pages that display user-specific content. ISR
+  regenerates the page for the first visitor after the revalidation window and caches the result for all subsequent
+  visitors.
+- **`use cache` / `unstable_cache`:** These directives cannot access `cookies()` or `headers()` directly. If you need to
+  cache part of an authenticated page, read cookies outside the cache scope and pass relevant values as arguments.
+
+> **Note:** Next.js caching defaults have changed across versions. For example,
+> [Next.js 15 changed `fetch` requests, `GET` Route Handlers, and the client Router Cache to be uncached by default](https://nextjs.org/blog/next-15#caching-semantics),
+> reversing the previous opt-out model. Check the [caching guide](https://nextjs.org/docs/app/guides/caching) for your
+> specific Next.js version.
+
+**Other SSR frameworks (Remix, Astro, SvelteKit, TanStack Start):** These frameworks do not cache SSR responses by
+default. If you add caching headers to improve performance, exclude routes that call `getUser()` or read auth cookies.
 
 ## License