@netlify/identity 0.3.1-alpha.6 → 0.4.2

package/README.md

@@ -8,6 +8,7 @@ This is NOT the Netlify Identity Widget. This library exports standalone async f
 **Prerequisites:**
 
 - [Netlify Identity](https://docs.netlify.com/security/secure-access-to-sites/identity/) must be enabled on your Netlify project
+- **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
@@ -37,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
 
@@ -301,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'
@@ -340,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`
 
@@ -352,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`
 
@@ -360,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`
 
@@ -370,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`
 
@@ -382,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
 
@@ -400,6 +401,7 @@ interface User {
   pictureUrl?: string
   roles?: string[]
   metadata?: Record<string, unknown>
+  appMetadata?: Record<string, unknown>
   rawGoTrueData?: Record<string, unknown>
 }
 ```
@@ -449,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`
 
@@ -485,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`
 
@@ -497,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`
 
@@ -1046,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

@@ -227,6 +227,24 @@ var triggerNextjsDynamic = () => {
   }
 };
 
+// src/fetch.ts
+var DEFAULT_TIMEOUT_MS = 5e3;
+var fetchWithTimeout = async (url, options = {}, timeoutMs = DEFAULT_TIMEOUT_MS) => {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    return await fetch(url, { ...options, signal: controller.signal });
+  } catch (error) {
+    if (error instanceof Error && error.name === "AbortError") {
+      const pathname = new URL(url).pathname;
+      throw new AuthError(`Identity request to ${pathname} timed out after ${timeoutMs}ms`);
+    }
+    throw error;
+  } finally {
+    clearTimeout(timer);
+  }
+};
+
 // src/events.ts
 var AUTH_EVENTS = {
   LOGIN: "login",
@@ -344,7 +362,7 @@ var refreshSession = async () => {
   }
   let res;
   try {
-    res = await fetch(`${identityUrl}/token`, {
+    res = await fetchWithTimeout(`${identityUrl}/token`, {
       method: "POST",
       headers: { "Content-Type": "application/x-www-form-urlencoded" },
       body: new URLSearchParams({ grant_type: "refresh_token", refresh_token: refreshToken }).toString()
@@ -398,7 +416,7 @@ var login = async (email, password) => {
     });
     let res;
     try {
-      res = await fetch(`${identityUrl}/token`, {
+      res = await fetchWithTimeout(`${identityUrl}/token`, {
         method: "POST",
         headers: { "Content-Type": "application/x-www-form-urlencoded" },
         body: body.toString()
@@ -414,7 +432,7 @@ var login = async (email, password) => {
     const accessToken = data.access_token;
     let userRes;
     try {
-      userRes = await fetch(`${identityUrl}/user`, {
+      userRes = await fetchWithTimeout(`${identityUrl}/user`, {
         headers: { Authorization: `Bearer ${accessToken}` }
       });
     } catch (error) {
@@ -448,7 +466,7 @@ var signup = async (email, password, data) => {
     const cookies = getCookies();
     let res;
     try {
-      res = await fetch(`${identityUrl}/signup`, {
+      res = await fetchWithTimeout(`${identityUrl}/signup`, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({ email, password, data })
@@ -495,7 +513,7 @@ var logout = async () => {
     const jwt = cookies.get(NF_JWT_COOKIE);
     if (jwt) {
       try {
-        await fetch(`${identityUrl}/logout`, {
+        await fetchWithTimeout(`${identityUrl}/logout`, {
           method: "POST",
           headers: { Authorization: `Bearer ${jwt}` }
         });
@@ -675,6 +693,7 @@ 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,
@@ -686,7 +705,8 @@ var toUser = (userData) => {
     pictureUrl: typeof pictureUrl === "string" ? pictureUrl : void 0,
     roles: toRoles(appMeta),
     metadata: userMeta,
-    rawGoTrueData: { ...userData }
+    appMetadata: appMeta,
+    rawGoTrueData: { ...safeUserData }
   };
 };
 var claimsToUser = (claims) => {
@@ -701,7 +721,8 @@ var claimsToUser = (claims) => {
     name: typeof name === "string" ? name : void 0,
     pictureUrl: typeof pictureUrl === "string" ? pictureUrl : void 0,
     roles: toRoles(appMeta),
-    metadata: userMeta
+    metadata: userMeta,
+    appMetadata: appMeta
   };
 };
 var decodeJwtPayload = (token) => {
@@ -716,7 +737,7 @@ var decodeJwtPayload = (token) => {
 };
 var fetchFullUser = async (identityUrl, jwt) => {
   try {
-    const res = await fetch(`${identityUrl}/user`, {
+    const res = await fetchWithTimeout(`${identityUrl}/user`, {
       headers: { Authorization: `Bearer ${jwt}` }
     });
     if (!res.ok) return null;
@@ -905,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) {
@@ -919,7 +953,7 @@ var adminFetch = async (path, options = {}) => {
   const { url, token } = getAdminAuth();
   let res;
   try {
-    res = await fetch(`${url}${path}`, {
+    res = await fetchWithTimeout(`${url}${path}`, {
       ...options,
       headers: {
         ...options.headers,
@@ -936,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: