@netlify/identity 0.4.1 → 0.4.2

package/README.md

@@ -38,6 +38,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
 
@@ -302,10 +303,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 +341,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 +353,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 +361,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`, `aud`, `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 +371,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 +383,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
 
@@ -451,14 +451,14 @@ interface AdminUserUpdates {
   email?: string
   password?: string
   role?: string
+  aud?: string
   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`, `aud`, force-confirm a user, and write to `app_metadata`. Only these typed fields are forwarded.
 
 #### `SignupData`
 
@@ -487,7 +487,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 +499,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`, `aud`, `app_metadata`, `user_metadata`) to the request body. Other keys are silently ignored.
 
 #### `Admin`
 
@@ -1048,6 +1048,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

@@ -926,6 +926,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 +970,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", "aud", "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", "aud", "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: