@netlify/identity 0.4.1 → 1.0.0

package/README.md

@@ -3,23 +3,24 @@
 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
 
@@ -38,6 +39,7 @@ This library provides a unified API that works in both browser and server contex
   - [Password recovery](#password-recovery)
   - [Invite acceptance](#invite-acceptance)
   - [Session lifetime](#session-lifetime)
+  - [Caching and authenticated content](#caching-and-authenticated-content)
 
 ## Installation
 
@@ -96,7 +98,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.
 
@@ -172,7 +174,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.
 
@@ -302,10 +304,9 @@ Updates the current user's metadata or credentials. Requires an active session.
 
 ### Admin Operations
 
-The `admin` namespace provides user management functions for administrators. These work in two contexts:
+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.
 
-- **Server:** Uses the operator token from the Netlify runtime for full admin access. No logged-in user required.
-- **Browser:** Uses the logged-in user's JWT. The user must have an admin role.
+Calling any admin method from a browser environment throws an `AuthError`.
 
 ```ts
 import { admin } from '@netlify/identity'
@@ -341,9 +342,9 @@ export default async (req: Request, context: Context) => {
 admin.listUsers(options?: ListUsersOptions): Promise<User[]>
 ```
 
-Lists all users. Pagination options are supported on the server; they are ignored in the browser.
+Lists all users. Pagination options (`page`, `perPage`) are forwarded as query parameters.
 
-**Throws:** `AuthError` if the operator token is missing (server) or no user is logged in (browser).
+**Throws:** `AuthError` if called from a browser, or if the operator token is missing.
 
 #### `admin.getUser`
 
@@ -353,7 +354,7 @@ admin.getUser(userId: string): Promise<User>
 
 Gets a single user by ID.
 
-**Throws:** `AuthError` if the user is not found, the operator token is missing (server), or no user is logged in (browser).
+**Throws:** `AuthError` if called from a browser, the user is not found, or the operator token is missing.
 
 #### `admin.createUser`
 
@@ -361,9 +362,9 @@ Gets a single user by ID.
 admin.createUser(params: CreateUserParams): Promise<User>
 ```
 
-Creates a new user. The user is auto-confirmed. Optional `data` is spread into the request body as additional attributes.
+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` on failure (e.g., email already exists).
+**Throws:** `AuthError` if called from a browser, the email already exists, or the operator token is missing.
 
 #### `admin.updateUser`
 
@@ -371,9 +372,9 @@ Creates a new user. The user is auto-confirmed. Optional `data` is spread into t
 admin.updateUser(userId: string, attributes: AdminUserUpdates): Promise<User>
 ```
 
-Updates an existing user by ID. Pass any attributes to change (e.g., `{ email: 'new@example.com' }`). See `AdminUserUpdates` for typed fields.
+Updates an existing user by ID. Only typed `AdminUserUpdates` fields are forwarded (e.g., `{ email: 'new@example.com' }`, `{ role: 'editor' }`).
 
-**Throws:** `AuthError` if the user is not found or the update fails.
+**Throws:** `AuthError` if called from a browser, the user is not found, or the update fails.
 
 #### `admin.deleteUser`
 
@@ -383,7 +384,7 @@ admin.deleteUser(userId: string): Promise<void>
 
 Deletes a user by ID.
 
-**Throws:** `AuthError` if the user is not found or the deletion fails.
+**Throws:** `AuthError` if called from a browser, the user is not found, or the deletion fails.
 
 ### Types
 
@@ -393,16 +394,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 +435,7 @@ interface IdentityConfig {
 #### `AuthProvider`
 
 ```ts
-type AuthProvider = 'google' | 'github' | 'gitlab' | 'bitbucket' | 'facebook' | 'saml' | 'email'
+type AuthProvider = 'google' | 'github' | 'gitlab' | 'bitbucket' | 'facebook' | 'email'
 ```
 
 #### `UserUpdates`
@@ -454,11 +461,10 @@ interface AdminUserUpdates {
   confirm?: boolean
   app_metadata?: Record<string, unknown>
   user_metadata?: Record<string, unknown>
-  [key: string]: unknown
 }
 ```
 
-Fields accepted by `admin.updateUser()`. Unlike `UserUpdates`, admin updates can set `role`, force-confirm a user, and write to `app_metadata`.
+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`
 
@@ -487,7 +493,7 @@ interface ListUsersOptions {
 }
 ```
 
-Pagination options for `admin.listUsers()`. Only used on the server; pagination is ignored in the browser.
+Pagination options for `admin.listUsers()`.
 
 #### `CreateUserParams`
 
@@ -499,7 +505,7 @@ interface CreateUserParams {
 }
 ```
 
-Parameters for `admin.createUser()`. Optional `data` is spread into the request body as top-level attributes (use it to set `app_metadata`, `user_metadata`, `role`, etc.).
+Parameters for `admin.createUser()`. Optional `data` forwards allowed fields (`role`, `app_metadata`, `user_metadata`) to the request body. Other keys are silently ignored.
 
 #### `Admin`
 
@@ -1048,6 +1054,20 @@ Sessions are managed by Netlify Identity on the server side. The library stores
 
 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.
+
+**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.
+
 ## License
 
 MIT

package/dist/index.cjs

@@ -56,7 +56,7 @@ __export(index_exports, {
 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 +681,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 +694,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 +727,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 +824,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) {
@@ -926,6 +931,19 @@ var updateUser = async (updates) => {
 };
 
 // src/admin.ts
+var SERVER_ONLY_MESSAGE = "Admin operations are server-only. Call admin methods from a Netlify Function or Edge Function, not from browser code.";
+var sanitizeUserId = (userId) => {
+  const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+  if (!uuidRegex.test(userId)) {
+    throw new AuthError("User ID is not a valid UUID");
+  }
+  return encodeURIComponent(userId);
+};
+var assertServer = () => {
+  if (isBrowser()) {
+    throw new AuthError(SERVER_ONLY_MESSAGE);
+  }
+};
 var getAdminAuth = () => {
   const ctx = getIdentityContext();
   if (!ctx?.url) {
@@ -957,105 +975,67 @@ var adminFetch = async (path, options = {}) => {
   }
   return res;
 };
-var getAdminUser = () => {
-  const client = getClient();
-  const user = client.currentUser();
-  if (!user) {
-    throw new AuthError("Admin operations require a logged-in user with admin role");
-  }
-  return user;
-};
 var listUsers = async (options) => {
-  if (!isBrowser()) {
-    const params = new URLSearchParams();
-    if (options?.page != null) params.set("page", String(options.page));
-    if (options?.perPage != null) params.set("per_page", String(options.perPage));
-    const query = params.toString();
-    const path = `/admin/users${query ? `?${query}` : ""}`;
-    const res = await adminFetch(path);
-    const body = await res.json();
-    return body.users.map(toUser);
-  }
-  try {
-    const user = getAdminUser();
-    const users = await user.admin.listUsers("");
-    return users.map(toUser);
-  } catch (error) {
-    if (error instanceof AuthError) throw error;
-    throw new AuthError(error.message, void 0, { cause: error });
-  }
+  assertServer();
+  const params = new URLSearchParams();
+  if (options?.page != null) params.set("page", String(options.page));
+  if (options?.perPage != null) params.set("per_page", String(options.perPage));
+  const query = params.toString();
+  const path = `/admin/users${query ? `?${query}` : ""}`;
+  const res = await adminFetch(path);
+  const body = await res.json();
+  return body.users.map(toUser);
 };
 var getUser2 = async (userId) => {
-  if (!isBrowser()) {
-    const res = await adminFetch(`/admin/users/${userId}`);
-    const userData = await res.json();
-    return toUser(userData);
-  }
-  try {
-    const user = getAdminUser();
-    const userData = await user.admin.getUser({ id: userId });
-    return toUser(userData);
-  } catch (error) {
-    if (error instanceof AuthError) throw error;
-    throw new AuthError(error.message, void 0, { cause: error });
-  }
+  assertServer();
+  const sanitizedUserId = sanitizeUserId(userId);
+  const res = await adminFetch(`/admin/users/${sanitizedUserId}`);
+  const userData = await res.json();
+  return toUser(userData);
 };
 var createUser = async (params) => {
-  if (!isBrowser()) {
-    const res = await adminFetch("/admin/users", {
-      method: "POST",
-      body: JSON.stringify({
-        email: params.email,
-        password: params.password,
-        ...params.data,
-        confirm: true
-      })
-    });
-    const userData = await res.json();
-    return toUser(userData);
-  }
-  try {
-    const user = getAdminUser();
-    const userData = await user.admin.createUser(params.email, params.password, {
-      ...params.data,
-      confirm: true
-    });
-    return toUser(userData);
-  } catch (error) {
-    if (error instanceof AuthError) throw error;
-    throw new AuthError(error.message, void 0, { cause: error });
+  assertServer();
+  const body = {
+    email: params.email,
+    password: params.password,
+    confirm: true
+  };
+  if (params.data) {
+    const allowedKeys = ["role", "app_metadata", "user_metadata"];
+    for (const key of allowedKeys) {
+      if (key in params.data) {
+        body[key] = params.data[key];
+      }
+    }
   }
+  const res = await adminFetch("/admin/users", {
+    method: "POST",
+    body: JSON.stringify(body)
+  });
+  const userData = await res.json();
+  return toUser(userData);
 };
 var updateUser2 = async (userId, attributes) => {
-  if (!isBrowser()) {
-    const res = await adminFetch(`/admin/users/${userId}`, {
-      method: "PUT",
-      body: JSON.stringify(attributes)
-    });
-    const userData = await res.json();
-    return toUser(userData);
-  }
-  try {
-    const user = getAdminUser();
-    const userData = await user.admin.updateUser({ id: userId }, attributes);
-    return toUser(userData);
-  } catch (error) {
-    if (error instanceof AuthError) throw error;
-    throw new AuthError(error.message, void 0, { cause: error });
+  assertServer();
+  const sanitizedUserId = sanitizeUserId(userId);
+  const body = {};
+  const allowedKeys = ["email", "password", "role", "confirm", "app_metadata", "user_metadata"];
+  for (const key of allowedKeys) {
+    if (key in attributes) {
+      body[key] = attributes[key];
+    }
   }
+  const res = await adminFetch(`/admin/users/${sanitizedUserId}`, {
+    method: "PUT",
+    body: JSON.stringify(body)
+  });
+  const userData = await res.json();
+  return toUser(userData);
 };
 var deleteUser = async (userId) => {
-  if (!isBrowser()) {
-    await adminFetch(`/admin/users/${userId}`, { method: "DELETE" });
-    return;
-  }
-  try {
-    const user = getAdminUser();
-    await user.admin.deleteUser({ id: userId });
-  } catch (error) {
-    if (error instanceof AuthError) throw error;
-    throw new AuthError(error.message, void 0, { cause: error });
-  }
+  assertServer();
+  const sanitizedUserId = sanitizeUserId(userId);
+  await adminFetch(`/admin/users/${sanitizedUserId}`, { method: "DELETE" });
 };
 var admin = { listUsers, getUser: getUser2, createUser, updateUser: updateUser2, deleteUser };
 // Annotate the CommonJS export names for ESM import in node: