@netlify/identity 0.4.2 → 1.1.0

package/README.md

@@ -3,33 +3,35 @@
 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.
 
-> **Status:** Beta. The API may change before 1.0.
-
 **Prerequisites:**
 
-- [Netlify Identity](https://docs.netlify.com/security/secure-access-to-sites/identity/) must be enabled on your Netlify project
+- [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
 
-| Package                                                                         | What it is                                     | When to use it                                                                             |
-| ------------------------------------------------------------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------ |
-| **`@netlify/identity`** (this library)                                          | Headless TypeScript API for browser and server | You want full control over your auth UI and need server-side auth (SSR, Netlify Functions) |
-| [`netlify-identity-widget`](https://github.com/netlify/netlify-identity-widget) | Pre-built login/signup modal (HTML + CSS)      | You want a drop-in UI component with no custom design                                      |
-| [`gotrue-js`](https://github.com/netlify/gotrue-js)                             | Low-level GoTrue HTTP client (browser only)    | You're building your own auth wrapper and need direct API access                           |
+`@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:
+
+| Package                                                                         | Status                           | What it was                                   |
+| ------------------------------------------------------------------------------- | -------------------------------- | --------------------------------------------- |
+| [`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)   |
 
-This library provides a unified API that works in both browser and server contexts, handles cookie management, and normalizes the user object. You do not need to install `gotrue-js` or the widget separately.
+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
+  - [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)
@@ -97,7 +99,7 @@ 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. In the browser or when the server can reach the Identity API, all fields are populated. When falling back to JWT claims (e.g., Identity API unreachable), fields like `createdAt`, `updatedAt`, `emailVerified`, and `rawGoTrueData` may be missing. 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.
 
@@ -173,7 +175,7 @@ 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'`, `'facebook'`, or `'saml'`.
+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.
 
@@ -241,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
@@ -361,7 +377,7 @@ 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`, `aud`, `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.
 
@@ -393,16 +409,22 @@ Deletes a user by ID.
 interface User {
   id: string
   email?: string
-  emailVerified?: boolean
+  confirmedAt?: string
   createdAt?: string
   updatedAt?: string
+  role?: string
   provider?: AuthProvider
   name?: string
   pictureUrl?: string
   roles?: string[]
-  metadata?: Record<string, unknown>
+  invitedAt?: string
+  confirmationSentAt?: string
+  recoverySentAt?: string
+  pendingEmail?: string
+  emailChangeSentAt?: string
+  lastSignInAt?: string
+  userMetadata?: Record<string, unknown>
   appMetadata?: Record<string, unknown>
-  rawGoTrueData?: Record<string, unknown>
 }
 ```
 
@@ -428,7 +450,7 @@ interface IdentityConfig {
 #### `AuthProvider`
 
 ```ts
-type AuthProvider = 'google' | 'github' | 'gitlab' | 'bitbucket' | 'facebook' | 'saml' | 'email'
+type AuthProvider = 'google' | 'github' | 'gitlab' | 'bitbucket' | 'facebook' | 'email'
 ```
 
 #### `UserUpdates`
@@ -451,14 +473,13 @@ interface AdminUserUpdates {
   email?: string
   password?: string
   role?: string
-  aud?: string
   confirm?: boolean
   app_metadata?: Record<string, unknown>
   user_metadata?: Record<string, unknown>
 }
 ```
 
-Fields accepted by `admin.updateUser()`. Unlike `UserUpdates`, admin updates can set `role`, `aud`, 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`
 
@@ -499,7 +520,7 @@ interface CreateUserParams {
 }
 ```
 
-Parameters for `admin.createUser()`. Optional `data` forwards allowed fields (`role`, `aud`, `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`
 
@@ -563,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`
@@ -582,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
@@ -655,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
@@ -687,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,12 +51,13 @@ __export(index_exports, {
   requestPasswordRecovery: () => requestPasswordRecovery,
   signup: () => signup,
   updateUser: () => updateUser,
-  verifyEmailChange: () => verifyEmailChange
+  verifyEmailChange: () => verifyEmailChange,
+  verifyRequestOrigin: () => verifyRequestOrigin
 });
 module.exports = __toCommonJS(index_exports);
 
 // src/types.ts
-var AUTH_PROVIDERS = ["google", "github", "gitlab", "bitbucket", "facebook", "saml", "email"];
+var AUTH_PROVIDERS = ["google", "github", "gitlab", "bitbucket", "facebook", "email"];
 
 // src/environment.ts
 var import_gotrue_js = __toESM(require("gotrue-js"), 1);
@@ -681,6 +682,7 @@ var hydrateSession = async () => {
 
 // src/user.ts
 var toAuthProvider = (value) => typeof value === "string" && AUTH_PROVIDERS.includes(value) ? value : void 0;
+var toOptionalString = (value) => typeof value === "string" && value !== "" ? value : void 0;
 var toRoles = (appMeta) => {
   const roles = appMeta.roles;
   if (Array.isArray(roles) && roles.every((r) => typeof r === "string")) {
@@ -693,20 +695,25 @@ var toUser = (userData) => {
   const appMeta = userData.app_metadata ?? {};
   const name = userMeta.full_name || userMeta.name;
   const pictureUrl = userMeta.avatar_url;
-  const { token: _token, ...safeUserData } = userData;
   return {
     id: userData.id,
     email: userData.email,
-    emailVerified: !!userData.confirmed_at,
+    confirmedAt: toOptionalString(userData.confirmed_at),
     createdAt: userData.created_at,
     updatedAt: userData.updated_at,
+    role: toOptionalString(userData.role),
     provider: toAuthProvider(appMeta.provider),
     name: typeof name === "string" ? name : void 0,
     pictureUrl: typeof pictureUrl === "string" ? pictureUrl : void 0,
     roles: toRoles(appMeta),
-    metadata: userMeta,
-    appMetadata: appMeta,
-    rawGoTrueData: { ...safeUserData }
+    invitedAt: toOptionalString(userData.invited_at),
+    confirmationSentAt: toOptionalString(userData.confirmation_sent_at),
+    recoverySentAt: toOptionalString(userData.recovery_sent_at),
+    pendingEmail: toOptionalString(userData.new_email),
+    emailChangeSentAt: toOptionalString(userData.email_change_sent_at),
+    lastSignInAt: toOptionalString(userData.last_sign_in_at),
+    userMetadata: userMeta,
+    appMetadata: appMeta
   };
 };
 var claimsToUser = (claims) => {
@@ -721,7 +728,7 @@ var claimsToUser = (claims) => {
     name: typeof name === "string" ? name : void 0,
     pictureUrl: typeof pictureUrl === "string" ? pictureUrl : void 0,
     roles: toRoles(appMeta),
-    metadata: userMeta,
+    userMetadata: userMeta,
     appMetadata: appMeta
   };
 };
@@ -818,8 +825,7 @@ var getSettings = async () => {
         gitlab: external.gitlab ?? false,
         bitbucket: external.bitbucket ?? false,
         facebook: external.facebook ?? false,
-        email: external.email ?? false,
-        saml: external.saml ?? false
+        email: external.email ?? false
       }
     };
   } catch (err) {
@@ -827,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();
@@ -996,7 +1014,7 @@ var createUser = async (params) => {
     confirm: true
   };
   if (params.data) {
-    const allowedKeys = ["role", "aud", "app_metadata", "user_metadata"];
+    const allowedKeys = ["role", "app_metadata", "user_metadata"];
     for (const key of allowedKeys) {
       if (key in params.data) {
         body[key] = params.data[key];
@@ -1014,7 +1032,7 @@ var updateUser2 = async (userId, attributes) => {
   assertServer();
   const sanitizedUserId = sanitizeUserId(userId);
   const body = {};
-  const allowedKeys = ["email", "password", "role", "aud", "confirm", "app_metadata", "user_metadata"];
+  const allowedKeys = ["email", "password", "role", "confirm", "app_metadata", "user_metadata"];
   for (const key of allowedKeys) {
     if (key in attributes) {
       body[key] = attributes[key];
@@ -1056,6 +1074,7 @@ var admin = { listUsers, getUser: getUser2, createUser, updateUser: updateUser2,
   requestPasswordRecovery,
   signup,
   updateUser,
-  verifyEmailChange
+  verifyEmailChange,
+  verifyRequestOrigin
 });
 //# sourceMappingURL=index.cjs.map