@netlify/identity 1.0.0 → 1.1.0

package/README.md

@@ -27,10 +27,11 @@ If you need a pre-built login UI, the widget still works. For everything else (c
 - [Installation](#installation)
 - [Quick start](#quick-start)
 - [API](#api)
-  - [Functions](#functions) -- `getUser`, `login`, `signup`, `logout`, `oauthLogin`, `handleAuthCallback`, `onAuthChange`, `hydrateSession`, `refreshSession`, and more
+  - [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`, etc.
+  - [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)
@@ -242,6 +243,20 @@ 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
@@ -569,6 +584,16 @@ The `token` field is only present for `invite` callbacks, where the user hasn't
 
 For all other types (`oauth`, `confirmation`, `recovery`, `email_change`), the user is logged in directly and `token` is not set.
 
+#### `VerifyRequestOriginOptions`
+
+```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
 
 #### `AuthError`
@@ -588,6 +613,45 @@ 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
@@ -661,11 +725,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
@@ -693,6 +758,8 @@ 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.
 
+> 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
 
 **Login from the browser (recommended):**

package/dist/index.cjs

@@ -51,7 +51,8 @@ __export(index_exports, {
   requestPasswordRecovery: () => requestPasswordRecovery,
   signup: () => signup,
   updateUser: () => updateUser,
-  verifyEmailChange: () => verifyEmailChange
+  verifyEmailChange: () => verifyEmailChange,
+  verifyRequestOrigin: () => verifyRequestOrigin
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -832,6 +833,18 @@ var getSettings = async () => {
   }
 };
 
+// src/csrf.ts
+var verifyRequestOrigin = (request, options) => {
+  const origin = request.headers.get("origin");
+  if (!origin) {
+    throw new AuthError("Cross-origin request refused: missing Origin header.", 403);
+  }
+  const allowed = options?.allowedOrigins ?? [new URL(request.url).origin];
+  if (!allowed.includes(origin)) {
+    throw new AuthError(`Cross-origin request refused: Origin ${origin} did not match an allowed origin.`, 403);
+  }
+};
+
 // src/account.ts
 var resolveCurrentUser = async () => {
   const client = getClient();
@@ -1061,6 +1074,7 @@ var admin = { listUsers, getUser: getUser2, createUser, updateUser: updateUser2,
   requestPasswordRecovery,
   signup,
   updateUser,
-  verifyEmailChange
+  verifyEmailChange,
+  verifyRequestOrigin
 });
 //# sourceMappingURL=index.cjs.map