@netlify/identity 0.3.0-alpha.7 → 0.3.1-alpha.0

package/README.md

@@ -1,6 +1,6 @@
 # @netlify/identity
 
-A lightweight, no-config headless authentication library for projects using Netlify Identity for browser and server. Uses [gotrue-js](https://github.com/netlify/gotrue-js) under the hood.
+A lightweight, no-config headless authentication library for projects using Netlify Identity. Works in both browser and server contexts.
 
 > **Status:** Beta. The API may change before 1.0.
 
@@ -17,14 +17,14 @@ A lightweight, no-config headless authentication library for projects using Netl
 | [`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                           |
 
-This library wraps `gotrue-js` in the browser and calls the GoTrue HTTP API directly on the server. It provides a unified API that works in both contexts, handles cookie management, and normalizes the user object. You do not need to install `gotrue-js` or the widget separately.
+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.
 
 ## Table of contents
 
 - [Installation](#installation)
 - [Quick start](#quick-start)
 - [API](#api)
-  - [Functions](#functions) -- `getUser`, `login`, `signup`, `logout`, `oauthLogin`, `handleAuthCallback`, `onAuthChange`, `hydrateSession`, and more
+  - [Functions](#functions) -- `getUser`, `login`, `signup`, `logout`, `oauthLogin`, `handleAuthCallback`, `onAuthChange`, `hydrateSession`, `refreshSession`, 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.
   - [Errors](#errors) -- `AuthError`, `MissingIdentityError`
@@ -132,7 +132,7 @@ login(email: string, password: string): Promise<User>
 
 Logs in with email and password. Works in both browser and server contexts.
 
-In the browser, uses gotrue-js and emits a `'login'` event. On the server (Netlify Functions, Edge Functions), calls the GoTrue HTTP API directly and sets the `nf_jwt` cookie via the Netlify runtime.
+In the browser, emits a `'login'` event. On the server (Netlify Functions, Edge Functions), calls the Identity API directly and sets the `nf_jwt` cookie via the Netlify runtime.
 
 **Throws:** `AuthError` on invalid credentials or network failure. In the browser, `MissingIdentityError` if Identity is not configured. On the server, `AuthError` if the Netlify Functions runtime is not available.
 
@@ -158,7 +158,7 @@ logout(): Promise<void>
 
 Logs out the current user and clears the session. Works in both browser and server contexts.
 
-In the browser, uses gotrue-js and emits a `'logout'` event. On the server, calls GoTrue's `/logout` endpoint with the JWT from the `nf_jwt` cookie, then deletes the cookie. Auth cookies are always cleared, even if the GoTrue call fails.
+In the browser, emits a `'logout'` event. On the server, calls the Identity `/logout` endpoint with the JWT from the `nf_jwt` cookie, then deletes the cookie. Auth cookies are always cleared, even if the server call fails.
 
 **Throws:** In the browser, `MissingIdentityError` if Identity is not configured. On the server, `AuthError` if the Netlify Functions runtime is not available.
 
@@ -198,11 +198,11 @@ Subscribes to auth state changes (login, logout, token refresh, user updates, an
 hydrateSession(): Promise<User | null>
 ```
 
-Bootstraps the browser-side gotrue-js session from server-set auth cookies (`nf_jwt`, `nf_refresh`). Returns the hydrated `User`, or `null` if no auth cookies are present. No-op on the server.
+Bootstraps the browser-side session from server-set auth cookies (`nf_jwt`, `nf_refresh`). Returns the hydrated `User`, or `null` if no auth cookies are present. No-op on the server.
 
-**When to use:** After a server-side login (e.g., via a Netlify Function or Server Action), the `nf_jwt` cookie is set but gotrue-js has no browser session yet. `getUser()` calls `hydrateSession()` automatically, but account operations like `updateUser()` or `verifyEmailChange()` require a live gotrue-js session. Call `hydrateSession()` explicitly if you need the session ready before calling those operations.
+**When to use:** After a server-side login (e.g., via a Netlify Function or Server Action), the `nf_jwt` cookie is set but no browser session exists yet. `getUser()` calls `hydrateSession()` automatically, but account operations like `updateUser()` or `verifyEmailChange()` require a live browser session. Call `hydrateSession()` explicitly if you need the session ready before calling those operations.
 
-If a gotrue-js session already exists (e.g., from a browser-side login), this is a no-op and returns the existing user.
+If a browser session already exists (e.g., from a browser-side login), this is a no-op and returns the existing user.
 
 ```ts
 import { hydrateSession, updateUser } from '@netlify/identity'
@@ -214,6 +214,30 @@ await hydrateSession()
 await updateUser({ data: { full_name: 'Jane Doe' } })
 ```
 
+#### `refreshSession`
+
+```ts
+refreshSession(): Promise<string | null>
+```
+
+Refreshes an expired or near-expired session. Returns the new access token on success, or `null` if no refresh is needed or the refresh token is invalid/missing.
+
+**Browser:** Checks if the current access token is near expiry and refreshes it if needed, syncing the new token to the `nf_jwt` cookie. Note: in the browser, the library automatically refreshes tokens in the background after `login()`, `hydrateSession()`, or `handleAuthCallback()`, so you typically don't need to call this manually.
+
+**Server:** Reads the `nf_jwt` and `nf_refresh` cookies. If the access token is expired or within 60 seconds of expiry, exchanges the refresh token for a new access token via the Identity `/token` endpoint and updates both cookies on the response. Call this in framework middleware or at the start of server-side request handlers to ensure the JWT is valid for downstream processing.
+
+**Throws:** `AuthError` on network failure or if the Identity endpoint URL cannot be determined. Does **not** throw for invalid/expired refresh tokens (returns `null` instead).
+
+```ts
+// Example: Astro middleware
+import { refreshSession } from '@netlify/identity'
+
+export async function onRequest(context, next) {
+  await refreshSession()
+  return next()
+}
+```
+
 #### `requestPasswordRecovery`
 
 ```ts
@@ -279,7 +303,7 @@ Updates the current user's metadata or credentials. Requires an active session.
 The `admin` namespace provides user management functions for administrators. These work in two contexts:
 
 - **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 via gotrue-js. The user must have an admin role.
+- **Browser:** Uses the logged-in user's JWT. The user must have an admin role.
 
 ```ts
 import { admin } from '@netlify/identity'
@@ -315,7 +339,7 @@ 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 (gotrue-js does not support pagination for this method).
+Lists all users. Pagination options are supported on the server; they are ignored in the browser.
 
 **Throws:** `AuthError` if the operator token is missing (server) or no user is logged in (browser).
 
@@ -460,7 +484,7 @@ interface ListUsersOptions {
 }
 ```
 
-Pagination options for `admin.listUsers()`. Only used on the server; pagination is ignored in the browser (gotrue-js limitation).
+Pagination options for `admin.listUsers()`. Only used on the server; pagination is ignored in the browser.
 
 #### `CreateUserParams`
 
@@ -472,7 +496,7 @@ interface CreateUserParams {
 }
 ```
 
-Parameters for `admin.createUser()`. Optional `data` is spread into the GoTrue request body as top-level attributes (use it to set `app_metadata`, `user_metadata`, `role`, etc.).
+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.).
 
 #### `Admin`
 
@@ -506,7 +530,7 @@ Constants for auth event names. Use these instead of string literals for type sa
 | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `LOGIN`         | `login()`, `signup()` (with autoconfirm), `recoverPassword()`, `handleAuthCallback()` (OAuth/confirmation), `hydrateSession()`                                                                                                                                                        |
 | `LOGOUT`        | `logout()`                                                                                                                                                                                                                                                                            |
-| `TOKEN_REFRESH` | gotrue-js refreshes an expiring access token in the background                                                                                                                                                                                                                        |
+| `TOKEN_REFRESH` | The library's auto-refresh timer refreshes an expiring access token and syncs the new token to the `nf_jwt` cookie. Fires automatically after `login()`, `hydrateSession()`, or `handleAuthCallback()` establishes a session.                                                         |
 | `USER_UPDATED`  | `updateUser()`, `verifyEmailChange()`, `handleAuthCallback()` (email change)                                                                                                                                                                                                          |
 | `RECOVERY`      | `handleAuthCallback()` (recovery token only). The user is authenticated but has **not** set a new password yet. Listen for this to redirect to a password reset form. `recoverPassword()` emits `LOGIN` instead because it completes both steps (token redemption + password change). |
 
@@ -564,7 +588,7 @@ For SSR frameworks (Next.js, Remix, Astro, TanStack Start), the recommended patt
 - **Browser-side** for auth mutations: `login()`, `signup()`, `logout()`, `oauthLogin()`
 - **Server-side** for reading auth state: `getUser()`, `getSettings()`, `getIdentityConfig()`
 
-Browser-side auth mutations call the GoTrue API directly from the browser, set the `nf_jwt` cookie and gotrue-js localStorage, and emit `onAuthChange` events. This keeps the client UI in sync immediately. Server-side reads work because the cookie is sent with every request.
+Browser-side auth mutations call the Identity API directly from the browser, set the `nf_jwt` cookie, and emit `onAuthChange` events. This keeps the client UI in sync immediately. Server-side reads work because the cookie is sent with every request.
 
 The library also supports server-side mutations (`login()`, `signup()`, `logout()` inside Netlify Functions), but these require the Netlify Functions runtime to set cookies. After a server-side mutation, you need a full page navigation so the browser sends the new cookie.
 
@@ -1010,14 +1034,16 @@ if (result?.type === 'invite' && result.token) {
 
 ### Session lifetime
 
-Sessions are managed by Netlify Identity (GoTrue) on the server side. The library stores two cookies:
+Sessions are managed by Netlify Identity on the server side. The library stores two cookies:
 
-- **`nf_jwt`**: A short-lived JWT access token (default: 1 hour). Automatically refreshed by gotrue-js in the browser using the refresh token.
+- **`nf_jwt`**: A short-lived JWT access token (default: 1 hour).
 - **`nf_refresh`**: A long-lived refresh token used to obtain new access tokens without re-authenticating.
 
-In the browser, gotrue-js handles token refresh automatically in the background. On the server, the access token in the `nf_jwt` cookie is validated as-is; if it has expired, `getUser()` returns `null`. The user will need to refresh the page (which triggers a browser-side token refresh) or log in again.
+**Browser auto-refresh:** After `login()`, `hydrateSession()`, or `handleAuthCallback()` establishes a session, the library automatically schedules a background refresh 60 seconds before the access token expires. When the refresh fires, it obtains a new access token, syncs it to the `nf_jwt` cookie, and emits a `TOKEN_REFRESH` event. This keeps the cookie fresh as long as the user has the tab open. If the refresh fails (e.g., the refresh token was revoked), the timer stops and the user will need to log in again.
+
+**Server-side refresh:** On the server, the access token in the `nf_jwt` cookie is validated as-is. If it has expired and no refresh happens, `getUser()` returns `null`. To handle this, call `refreshSession()` in your framework middleware or request handler. This checks if the token is near expiry, exchanges the refresh token for a new one, and updates the cookies on the response.
 
-Session lifetime is configured in your GoTrue/Identity server settings, not in this library.
+Session lifetime is configured in your Netlify Identity settings, not in this library.
 
 ## License
 

package/dist/index.cjs

@@ -47,6 +47,7 @@ __export(index_exports, {
   oauthLogin: () => oauthLogin,
   onAuthChange: () => onAuthChange,
   recoverPassword: () => recoverPassword,
+  refreshSession: () => refreshSession,
   requestPasswordRecovery: () => requestPasswordRecovery,
   signup: () => signup,
   updateUser: () => updateUser,
@@ -271,6 +272,90 @@ var onAuthChange = (callback) => {
   };
 };
 
+// src/refresh.ts
+var REFRESH_MARGIN_S = 60;
+var refreshTimer = null;
+var startTokenRefresh = () => {
+  if (!isBrowser()) return;
+  stopTokenRefresh();
+  const client = getGoTrueClient();
+  const user = client?.currentUser();
+  if (!user) return;
+  const token = user.tokenDetails();
+  if (!token?.expires_at) return;
+  const nowS = Math.floor(Date.now() / 1e3);
+  const expiresAtS = typeof token.expires_at === "number" && token.expires_at > 1e12 ? Math.floor(token.expires_at / 1e3) : token.expires_at;
+  const delayMs = Math.max(0, expiresAtS - nowS - REFRESH_MARGIN_S) * 1e3;
+  refreshTimer = setTimeout(async () => {
+    try {
+      const freshJwt = await user.jwt(true);
+      const freshDetails = user.tokenDetails();
+      setBrowserAuthCookies(freshJwt, freshDetails?.refresh_token);
+      emitAuthEvent(AUTH_EVENTS.TOKEN_REFRESH, toUser(user));
+      startTokenRefresh();
+    } catch {
+      stopTokenRefresh();
+    }
+  }, delayMs);
+};
+var stopTokenRefresh = () => {
+  if (refreshTimer !== null) {
+    clearTimeout(refreshTimer);
+    refreshTimer = null;
+  }
+};
+var refreshSession = async () => {
+  if (isBrowser()) {
+    const client = getGoTrueClient();
+    const user = client?.currentUser();
+    if (!user) return null;
+    try {
+      const jwt = await user.jwt();
+      setBrowserAuthCookies(jwt, user.tokenDetails()?.refresh_token);
+      return jwt;
+    } catch {
+      return null;
+    }
+  }
+  const accessToken = getServerCookie(NF_JWT_COOKIE);
+  const refreshToken = getServerCookie(NF_REFRESH_COOKIE);
+  if (!accessToken || !refreshToken) return null;
+  const decoded = decodeJwtPayload(accessToken);
+  if (!decoded?.exp) return null;
+  const nowS = Math.floor(Date.now() / 1e3);
+  if (decoded.exp - nowS > REFRESH_MARGIN_S) {
+    return null;
+  }
+  const ctx = getIdentityContext();
+  const identityUrl = ctx?.url ?? (globalThis.Netlify?.context?.url ? new URL(IDENTITY_PATH, globalThis.Netlify.context.url).href : null);
+  if (!identityUrl) {
+    throw new AuthError("Could not determine the Identity endpoint URL for token refresh");
+  }
+  let res;
+  try {
+    res = await fetch(`${identityUrl}/token`, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: `grant_type=refresh_token&refresh_token=${refreshToken}`
+    });
+  } catch (error) {
+    throw AuthError.from(error);
+  }
+  if (!res.ok) {
+    const errorBody = await res.json().catch(() => ({}));
+    if (res.status === 401 || res.status === 400) {
+      return null;
+    }
+    throw new AuthError(errorBody.msg || `Token refresh failed (${res.status})`, res.status);
+  }
+  const data = await res.json();
+  const cookies = globalThis.Netlify?.context?.cookies;
+  if (cookies) {
+    setAuthCookies(cookies, data.access_token, data.refresh_token);
+  }
+  return data.access_token;
+};
+
 // src/auth.ts
 var getCookies = () => {
   const cookies = globalThis.Netlify?.context?.cookies;
@@ -335,6 +420,7 @@ var login = async (email, password) => {
     const jwt = await gotrueUser.jwt();
     setBrowserAuthCookies(jwt, gotrueUser.tokenDetails()?.refresh_token);
     const user = toUser(gotrueUser);
+    startTokenRefresh();
     emitAuthEvent(AUTH_EVENTS.LOGIN, user);
     return user;
   } catch (error) {
@@ -379,6 +465,7 @@ var signup = async (email, password, data) => {
         const refreshToken = response.tokenDetails?.()?.refresh_token;
         setBrowserAuthCookies(jwt, refreshToken);
       }
+      startTokenRefresh();
       emitAuthEvent(AUTH_EVENTS.LOGIN, user);
     }
     return user;
@@ -410,6 +497,7 @@ var logout = async () => {
       await currentUser.logout();
     }
     deleteBrowserAuthCookies();
+    stopTokenRefresh();
     emitAuthEvent(AUTH_EVENTS.LOGOUT, null);
   } catch (error) {
     throw AuthError.from(error);
@@ -462,6 +550,7 @@ var handleOAuthCallback = async (client, params, accessToken) => {
   );
   setBrowserAuthCookies(accessToken, refreshToken || void 0);
   const user = toUser(gotrueUser);
+  startTokenRefresh();
   clearHash();
   emitAuthEvent(AUTH_EVENTS.LOGIN, user);
   return { type: "oauth", user };
@@ -471,6 +560,7 @@ var handleConfirmationCallback = async (client, token) => {
   const jwt = await gotrueUser.jwt();
   setBrowserAuthCookies(jwt, gotrueUser.tokenDetails()?.refresh_token);
   const user = toUser(gotrueUser);
+  startTokenRefresh();
   clearHash();
   emitAuthEvent(AUTH_EVENTS.LOGIN, user);
   return { type: "confirmation", user };
@@ -480,6 +570,7 @@ var handleRecoveryCallback = async (client, token) => {
   const jwt = await gotrueUser.jwt();
   setBrowserAuthCookies(jwt, gotrueUser.tokenDetails()?.refresh_token);
   const user = toUser(gotrueUser);
+  startTokenRefresh();
   clearHash();
   emitAuthEvent(AUTH_EVENTS.RECOVERY, user);
   return { type: "recovery", user };
@@ -547,6 +638,7 @@ var hydrateSession = async () => {
     return null;
   }
   const user = toUser(gotrueUser);
+  startTokenRefresh();
   emitAuthEvent(AUTH_EVENTS.LOGIN, user);
   return user;
 };
@@ -943,6 +1035,7 @@ var admin = { listUsers, getUser: getUser2, createUser, updateUser: updateUser2,
   oauthLogin,
   onAuthChange,
   recoverPassword,
+  refreshSession,
   requestPasswordRecovery,
   signup,
   updateUser,