@netlify/identity 0.4.2 → 1.1.0

package/dist/index.d.cts

@@ -1,10 +1,10 @@
 /** The supported OAuth and authentication providers. */
-declare const AUTH_PROVIDERS: readonly ["google", "github", "gitlab", "bitbucket", "facebook", "saml", "email"];
+declare const AUTH_PROVIDERS: readonly ["google", "github", "gitlab", "bitbucket", "facebook", "email"];
 /** A supported authentication provider name (e.g., `'google'`, `'github'`, `'email'`). */
 type AuthProvider = (typeof AUTH_PROVIDERS)[number];
 /**
  * Provider and role metadata stored in a user's `app_metadata` field.
- * GoTrue sets `provider` automatically on signup; `roles` controls authorization.
+ * The `provider` field is set automatically on signup; `roles` controls authorization.
  * Additional keys may be present depending on your Identity configuration.
  *
  * @example
@@ -27,7 +27,7 @@ interface AppMetadata {
  * On the server, `token` is the operator token for admin operations.
  */
 interface IdentityConfig {
-    /** The GoTrue API endpoint URL (e.g., `https://example.com/.netlify/identity`). */
+    /** The Identity API endpoint URL (e.g., `https://example.com/.netlify/identity`). */
     url: string;
     /** Operator token for server-side admin requests. Only available in Netlify Functions. */
     token?: string;
@@ -86,8 +86,6 @@ interface AdminUserUpdates {
     password?: string;
     /** The user's role (e.g., `'admin'`, `'editor'`). */
     role?: string;
-    /** The user's audience (rarely needed; defaults to the site's audience). */
-    aud?: string;
     /** Set to `true` to force-confirm the user's email without sending a confirmation email. */
     confirm?: boolean;
     /** Server-managed metadata. Only writable via admin operations. */
@@ -107,8 +105,8 @@ interface ListUsersOptions {
 /**
  * Parameters for {@link admin.createUser}.
  *
- * The optional `data` fields are forwarded as top-level attributes in the GoTrue
- * request body. Only these keys are accepted: `role`, `aud`, `app_metadata`,
+ * The optional `data` fields are forwarded as top-level attributes in the Identity API
+ * request body. Only these keys are accepted: `role`, `app_metadata`,
  * `user_metadata`. Any other keys are silently ignored. `data` cannot override
  * `email`, `password`, or `confirm`.
  *
@@ -124,14 +122,18 @@ interface ListUsersOptions {
 interface CreateUserParams {
     email: string;
     password: string;
-    /** GoTrue user fields: `role`, `aud`, `app_metadata`, `user_metadata`. Other keys are ignored. */
+    /** Identity user fields: `role`, `app_metadata`, `user_metadata`. Other keys are ignored. */
     data?: Record<string, unknown>;
 }
 
 /**
  * A normalized user object returned by all auth and admin functions.
  * Provides a consistent shape regardless of whether the user was loaded
- * from gotrue-js, a JWT cookie, or the server-side identity context.
+ * from the Identity API, a JWT cookie, or the server-side identity context.
+ *
+ * All fields except `id` are optional and may be `undefined`. Empty strings
+ * are normalized to `undefined`. State-dependent fields (invite,
+ * recovery, email-change) are only present when the user is in that state.
  *
  * @example
  * ```ts
@@ -142,30 +144,46 @@ interface CreateUserParams {
  * ```
  */
 interface User {
-    /** The user's unique identifier (GoTrue UUID). */
+    /** The user's unique identifier. */
     id: string;
     /** The user's email address. */
     email?: string;
-    /** `true` if the user's email has been confirmed. */
-    emailVerified?: boolean;
+    /** ISO 8601 timestamp of when the user's email was confirmed. `undefined` if not yet confirmed. */
+    confirmedAt?: string;
     /** ISO 8601 timestamp of when the account was created. */
     createdAt?: string;
     /** ISO 8601 timestamp of the last account update. */
     updatedAt?: string;
-    /** The authentication provider used to create the account. */
+    /**
+     * The account-level role string (e.g., `"admin"`). This is a single value
+     * set via the admin API, distinct from `roles` which is an array in `app_metadata`.
+     * `undefined` when not set or empty.
+     */
+    role?: string;
+    /** The authentication provider used to create the account (from `app_metadata.provider`). */
     provider?: AuthProvider;
     /** Display name from `user_metadata.full_name` or `user_metadata.name`. */
     name?: string;
     /** Avatar URL from `user_metadata.avatar_url`. */
     pictureUrl?: string;
-    /** Roles from `app_metadata.roles`, set via the admin API or Netlify UI. */
+    /** Application-level roles from `app_metadata.roles`, set via the admin API or Netlify UI. */
     roles?: string[];
-    /** The full `user_metadata` object. */
-    metadata?: Record<string, unknown>;
-    /** The full `app_metadata` object. */
+    /** ISO 8601 timestamp of when the user was invited. Only present if the user was created via invitation. */
+    invitedAt?: string;
+    /** ISO 8601 timestamp of when the confirmation email was last sent. */
+    confirmationSentAt?: string;
+    /** ISO 8601 timestamp of when the recovery email was last sent. */
+    recoverySentAt?: string;
+    /** The pending email address during an email change flow. Only present while the change is awaiting confirmation. */
+    pendingEmail?: string;
+    /** ISO 8601 timestamp of when the email change verification was last sent. */
+    emailChangeSentAt?: string;
+    /** ISO 8601 timestamp of the user's most recent sign-in. */
+    lastSignInAt?: string;
+    /** Custom user metadata. Contains profile data like `full_name` and `avatar_url`, and any custom fields set via `updateUser()`. */
+    userMetadata?: Record<string, unknown>;
+    /** Application metadata managed by the server. Contains `provider`, `roles`, and other system-managed fields. */
     appMetadata?: Record<string, unknown>;
-    /** The raw GoTrue user data, for accessing fields not mapped to this interface. */
-    rawGoTrueData?: Record<string, unknown>;
 }
 /**
  * Returns the currently authenticated user, or `null` if not logged in.
@@ -175,11 +193,11 @@ interface User {
  * (email, roles, timestamps, metadata, etc.) regardless of whether the
  * call happens in the browser or on the server.
  *
- * In the browser, checks gotrue-js localStorage first. If no localStorage
+ * In the browser, checks localStorage first. If no localStorage
  * session exists, hydrates from the `nf_jwt` cookie (set by server-side login).
  *
- * On the server, fetches the full user from GoTrue using the JWT from
- * the request. Falls back to JWT claims if GoTrue is unreachable.
+ * On the server, fetches the full user from the Identity API using the JWT from
+ * the request. Falls back to JWT claims if the Identity API is unreachable.
  *
  * On the server in a Next.js App Router context, calls `headers()` from
  * `next/headers` to opt the route into dynamic rendering. Without this,
@@ -260,6 +278,10 @@ declare const onAuthChange: (callback: AuthCallback) => (() => void);
  * try/catch. Next.js implements `redirect()` by throwing a special error; wrapping it in
  * try/catch will swallow the redirect.
  *
+ * **Server-side CSRF:** When called from a server endpoint, the endpoint must have CSRF
+ * protection. If your framework does not check the request's `Origin` by default, call
+ * {@link verifyRequestOrigin} at the start of the handler before invoking `login()`.
+ *
  * @example
  * ```ts
  * // Next.js server action
@@ -277,6 +299,11 @@ declare const login: (email: string, password: string) => Promise<User>;
  * In that case, no cookies are set and no auth event is emitted.
  *
  * @throws {AuthError} On duplicate email, validation failure, network error, or missing Netlify runtime.
+ *
+ * @remarks
+ * **Server-side CSRF:** When called from a server endpoint, the endpoint must have CSRF
+ * protection. If your framework does not check the request's `Origin` by default, call
+ * {@link verifyRequestOrigin} at the start of the handler before invoking `signup()`.
  */
 declare const signup: (email: string, password: string, data?: SignupData) => Promise<User>;
 /**
@@ -286,6 +313,11 @@ declare const signup: (email: string, password: string, data?: SignupData) => Pr
  * invalidation request fails. In the browser, emits a `'logout'` event via {@link onAuthChange}.
  *
  * @throws {AuthError} On missing Netlify runtime (server) or logout failure (browser).
+ *
+ * @remarks
+ * **Server-side CSRF:** When called from a server endpoint, the endpoint must have CSRF
+ * protection. If your framework does not check the request's `Origin` by default, call
+ * {@link verifyRequestOrigin} at the start of the handler before invoking `logout()`.
  */
 declare const logout: () => Promise<void>;
 /**
@@ -343,7 +375,7 @@ interface CallbackResult {
  */
 declare const handleAuthCallback: () => Promise<CallbackResult | null>;
 /**
- * Hydrates the browser-side gotrue-js session from server-set auth cookies.
+ * Hydrates the browser-side session from server-set auth cookies.
  * Call this on page load when using server-side login to enable browser
  * account operations (updateUser, verifyEmailChange, etc.).
  *
@@ -388,7 +420,7 @@ declare const refreshSession: () => Promise<string | null>;
  * Thrown by auth operations when something goes wrong: invalid credentials,
  * network failures, missing runtime context, etc.
  *
- * The `status` field contains the HTTP status code from GoTrue when available
+ * The `status` field contains the HTTP status code from the Identity API when available
  * (e.g., 401 for bad credentials, 422 for validation errors).
  * The `cause` field preserves the original error for debugging.
  *
@@ -405,7 +437,7 @@ declare const refreshSession: () => Promise<string | null>;
  */
 declare class AuthError extends Error {
     name: string;
-    /** HTTP status code from GoTrue, if the error originated from an API response. */
+    /** HTTP status code from the Identity API, if the error originated from an API response. */
     status?: number;
     cause?: unknown;
     constructor(message: string, status?: number, options?: {
@@ -414,7 +446,7 @@ declare class AuthError extends Error {
     static from(error: unknown): AuthError;
 }
 /**
- * Thrown when a function requires a gotrue-js client but Netlify Identity
+ * Thrown when a function requires the Identity client but Netlify Identity
  * is not configured (no endpoint URL could be discovered).
  *
  * This typically means the site does not have Identity enabled, or the app
@@ -425,6 +457,63 @@ declare class MissingIdentityError extends Error {
     constructor(message?: string);
 }
 
+/**
+ * Options for {@link verifyRequestOrigin}.
+ */
+interface VerifyRequestOriginOptions {
+    /**
+     * Origins that are allowed to make state-changing requests to this endpoint.
+     *
+     * If omitted, the request is only accepted from its own origin (the origin of `request.url`),
+     * which is the right default for sites whose login form and login endpoint live on the same origin.
+     *
+     * Pass an explicit list when you trust additional origins (for example, a separate frontend domain
+     * posting to an API on another domain). The list replaces the default, so it must include every
+     * origin you want to allow, including the request's own origin if applicable.
+     *
+     * Each value should be a full origin string with scheme and host: `'https://example.com'`.
+     */
+    allowedOrigins?: string[];
+}
+/**
+ * Same-origin check for state-changing requests, can be used to defend against Cross-Site Request
+ * Forgery (CSRF) on server-side endpoints that call {@link login}, {@link signup}, or {@link logout}.
+ *
+ * Compares the incoming request's `Origin` header against the request's own origin (or an explicit
+ * allowlist via `options.allowedOrigins`) and throws if they don't match. Call this at the start of
+ * any server-side handler that performs an auth mutation, before invoking the auth function.
+ *
+ * The check runs unconditionally on every call: any HTTP method, with or without an `Origin` header.
+ * If you don't want the check to apply to a given method or path, simply don't call the helper there.
+ *
+ * @throws {AuthError} with status `403` when the request has no `Origin` header.
+ * @throws {AuthError} with status `403` when the request's `Origin` is not in the allowed origins.
+ *
+ * @example
+ * ```ts
+ * // Netlify Function
+ * 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' } })
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Allow a separate trusted origin (e.g. a marketing site posting to an app domain).
+ * // The list replaces the default, so include the request's own origin if you still want it allowed.
+ * verifyRequestOrigin(request, {
+ *   allowedOrigins: ['https://app.example.com', 'https://www.example.com'],
+ * })
+ * ```
+ */
+declare const verifyRequestOrigin: (request: Request, options?: VerifyRequestOriginOptions) => void;
+
 /**
  * The admin namespace for privileged user management operations.
  * All methods are server-only and require the operator token
@@ -436,7 +525,7 @@ interface Admin {
     /**
      * Lists all users. Server-only.
      *
-     * Calls GoTrue `GET /admin/users` with the operator token. Pagination
+     * Calls `GET /admin/users` with the operator token. Pagination
      * options (`page`, `perPage`) are forwarded as query parameters.
      *
      * @throws {AuthError} If called from a browser, or if the operator token is missing.
@@ -445,7 +534,7 @@ interface Admin {
     /**
      * Gets a single user by ID. Server-only.
      *
-     * Calls GoTrue `GET /admin/users/:id` with the operator token.
+     * Calls `GET /admin/users/:id` with the operator token.
      *
      * @throws {AuthError} If called from a browser, the user is not found,
      *   or the operator token is missing.
@@ -455,12 +544,12 @@ interface Admin {
      * Creates a new user. The user is auto-confirmed (no confirmation email is sent).
      * Server-only.
      *
-     * The optional `data` fields are forwarded as top-level attributes in the GoTrue
-     * request body. Accepted fields: `role`, `aud`, `app_metadata`, `user_metadata`.
+     * The optional `data` fields are forwarded as top-level attributes in the Identity API
+     * request body. Accepted fields: `role`, `app_metadata`, `user_metadata`.
      * Any other keys in `data` are silently ignored. `data` cannot override `email`,
      * `password`, or `confirm`.
      *
-     * Calls GoTrue `POST /admin/users` with the operator token.
+     * Calls `POST /admin/users` with the operator token.
      *
      * @throws {AuthError} If called from a browser, the email already exists,
      *   or the operator token is missing.
@@ -469,7 +558,7 @@ interface Admin {
     /**
      * Updates an existing user by ID. Server-only.
      *
-     * Calls GoTrue `PUT /admin/users/:id` with the operator token.
+     * Calls `PUT /admin/users/:id` with the operator token.
      *
      * @throws {AuthError} If called from a browser, the user is not found,
      *   the update fails, or the operator token is missing.
@@ -478,7 +567,7 @@ interface Admin {
     /**
      * Deletes a user by ID. Server-only.
      *
-     * Calls GoTrue `DELETE /admin/users/:id` with the operator token.
+     * Calls `DELETE /admin/users/:id` with the operator token.
      *
      * @throws {AuthError} If called from a browser, the user is not found,
      *   the deletion fails, or the operator token is missing.
@@ -528,4 +617,4 @@ declare const verifyEmailChange: (token: string) => Promise<User>;
  */
 declare const updateUser: (updates: UserUpdates) => Promise<User>;
 
-export { AUTH_EVENTS, type Admin, type AdminUserUpdates, type AppMetadata, type AuthCallback, AuthError, type AuthEvent, type AuthProvider, type CallbackResult, type CreateUserParams, type IdentityConfig, type ListUsersOptions, MissingIdentityError, type Settings, type SignupData, type User, type UserUpdates, acceptInvite, admin, confirmEmail, getIdentityConfig, getSettings, getUser, handleAuthCallback, hydrateSession, isAuthenticated, login, logout, oauthLogin, onAuthChange, recoverPassword, refreshSession, requestPasswordRecovery, signup, updateUser, verifyEmailChange };
+export { AUTH_EVENTS, type Admin, type AdminUserUpdates, type AppMetadata, type AuthCallback, AuthError, type AuthEvent, type AuthProvider, type CallbackResult, type CreateUserParams, type IdentityConfig, type ListUsersOptions, MissingIdentityError, type Settings, type SignupData, type User, type UserUpdates, type VerifyRequestOriginOptions, acceptInvite, admin, confirmEmail, getIdentityConfig, getSettings, getUser, handleAuthCallback, hydrateSession, isAuthenticated, login, logout, oauthLogin, onAuthChange, recoverPassword, refreshSession, requestPasswordRecovery, signup, updateUser, verifyEmailChange, verifyRequestOrigin };

package/dist/index.d.ts

@@ -1,10 +1,10 @@
 /** The supported OAuth and authentication providers. */
-declare const AUTH_PROVIDERS: readonly ["google", "github", "gitlab", "bitbucket", "facebook", "saml", "email"];
+declare const AUTH_PROVIDERS: readonly ["google", "github", "gitlab", "bitbucket", "facebook", "email"];
 /** A supported authentication provider name (e.g., `'google'`, `'github'`, `'email'`). */
 type AuthProvider = (typeof AUTH_PROVIDERS)[number];
 /**
  * Provider and role metadata stored in a user's `app_metadata` field.
- * GoTrue sets `provider` automatically on signup; `roles` controls authorization.
+ * The `provider` field is set automatically on signup; `roles` controls authorization.
  * Additional keys may be present depending on your Identity configuration.
  *
  * @example
@@ -27,7 +27,7 @@ interface AppMetadata {
  * On the server, `token` is the operator token for admin operations.
  */
 interface IdentityConfig {
-    /** The GoTrue API endpoint URL (e.g., `https://example.com/.netlify/identity`). */
+    /** The Identity API endpoint URL (e.g., `https://example.com/.netlify/identity`). */
     url: string;
     /** Operator token for server-side admin requests. Only available in Netlify Functions. */
     token?: string;
@@ -86,8 +86,6 @@ interface AdminUserUpdates {
     password?: string;
     /** The user's role (e.g., `'admin'`, `'editor'`). */
     role?: string;
-    /** The user's audience (rarely needed; defaults to the site's audience). */
-    aud?: string;
     /** Set to `true` to force-confirm the user's email without sending a confirmation email. */
     confirm?: boolean;
     /** Server-managed metadata. Only writable via admin operations. */
@@ -107,8 +105,8 @@ interface ListUsersOptions {
 /**
  * Parameters for {@link admin.createUser}.
  *
- * The optional `data` fields are forwarded as top-level attributes in the GoTrue
- * request body. Only these keys are accepted: `role`, `aud`, `app_metadata`,
+ * The optional `data` fields are forwarded as top-level attributes in the Identity API
+ * request body. Only these keys are accepted: `role`, `app_metadata`,
  * `user_metadata`. Any other keys are silently ignored. `data` cannot override
  * `email`, `password`, or `confirm`.
  *
@@ -124,14 +122,18 @@ interface ListUsersOptions {
 interface CreateUserParams {
     email: string;
     password: string;
-    /** GoTrue user fields: `role`, `aud`, `app_metadata`, `user_metadata`. Other keys are ignored. */
+    /** Identity user fields: `role`, `app_metadata`, `user_metadata`. Other keys are ignored. */
     data?: Record<string, unknown>;
 }
 
 /**
  * A normalized user object returned by all auth and admin functions.
  * Provides a consistent shape regardless of whether the user was loaded
- * from gotrue-js, a JWT cookie, or the server-side identity context.
+ * from the Identity API, a JWT cookie, or the server-side identity context.
+ *
+ * All fields except `id` are optional and may be `undefined`. Empty strings
+ * are normalized to `undefined`. State-dependent fields (invite,
+ * recovery, email-change) are only present when the user is in that state.
  *
  * @example
  * ```ts
@@ -142,30 +144,46 @@ interface CreateUserParams {
  * ```
  */
 interface User {
-    /** The user's unique identifier (GoTrue UUID). */
+    /** The user's unique identifier. */
     id: string;
     /** The user's email address. */
     email?: string;
-    /** `true` if the user's email has been confirmed. */
-    emailVerified?: boolean;
+    /** ISO 8601 timestamp of when the user's email was confirmed. `undefined` if not yet confirmed. */
+    confirmedAt?: string;
     /** ISO 8601 timestamp of when the account was created. */
     createdAt?: string;
     /** ISO 8601 timestamp of the last account update. */
     updatedAt?: string;
-    /** The authentication provider used to create the account. */
+    /**
+     * The account-level role string (e.g., `"admin"`). This is a single value
+     * set via the admin API, distinct from `roles` which is an array in `app_metadata`.
+     * `undefined` when not set or empty.
+     */
+    role?: string;
+    /** The authentication provider used to create the account (from `app_metadata.provider`). */
     provider?: AuthProvider;
     /** Display name from `user_metadata.full_name` or `user_metadata.name`. */
     name?: string;
     /** Avatar URL from `user_metadata.avatar_url`. */
     pictureUrl?: string;
-    /** Roles from `app_metadata.roles`, set via the admin API or Netlify UI. */
+    /** Application-level roles from `app_metadata.roles`, set via the admin API or Netlify UI. */
     roles?: string[];
-    /** The full `user_metadata` object. */
-    metadata?: Record<string, unknown>;
-    /** The full `app_metadata` object. */
+    /** ISO 8601 timestamp of when the user was invited. Only present if the user was created via invitation. */
+    invitedAt?: string;
+    /** ISO 8601 timestamp of when the confirmation email was last sent. */
+    confirmationSentAt?: string;
+    /** ISO 8601 timestamp of when the recovery email was last sent. */
+    recoverySentAt?: string;
+    /** The pending email address during an email change flow. Only present while the change is awaiting confirmation. */
+    pendingEmail?: string;
+    /** ISO 8601 timestamp of when the email change verification was last sent. */
+    emailChangeSentAt?: string;
+    /** ISO 8601 timestamp of the user's most recent sign-in. */
+    lastSignInAt?: string;
+    /** Custom user metadata. Contains profile data like `full_name` and `avatar_url`, and any custom fields set via `updateUser()`. */
+    userMetadata?: Record<string, unknown>;
+    /** Application metadata managed by the server. Contains `provider`, `roles`, and other system-managed fields. */
     appMetadata?: Record<string, unknown>;
-    /** The raw GoTrue user data, for accessing fields not mapped to this interface. */
-    rawGoTrueData?: Record<string, unknown>;
 }
 /**
  * Returns the currently authenticated user, or `null` if not logged in.
@@ -175,11 +193,11 @@ interface User {
  * (email, roles, timestamps, metadata, etc.) regardless of whether the
  * call happens in the browser or on the server.
  *
- * In the browser, checks gotrue-js localStorage first. If no localStorage
+ * In the browser, checks localStorage first. If no localStorage
  * session exists, hydrates from the `nf_jwt` cookie (set by server-side login).
  *
- * On the server, fetches the full user from GoTrue using the JWT from
- * the request. Falls back to JWT claims if GoTrue is unreachable.
+ * On the server, fetches the full user from the Identity API using the JWT from
+ * the request. Falls back to JWT claims if the Identity API is unreachable.
  *
  * On the server in a Next.js App Router context, calls `headers()` from
  * `next/headers` to opt the route into dynamic rendering. Without this,
@@ -260,6 +278,10 @@ declare const onAuthChange: (callback: AuthCallback) => (() => void);
  * try/catch. Next.js implements `redirect()` by throwing a special error; wrapping it in
  * try/catch will swallow the redirect.
  *
+ * **Server-side CSRF:** When called from a server endpoint, the endpoint must have CSRF
+ * protection. If your framework does not check the request's `Origin` by default, call
+ * {@link verifyRequestOrigin} at the start of the handler before invoking `login()`.
+ *
  * @example
  * ```ts
  * // Next.js server action
@@ -277,6 +299,11 @@ declare const login: (email: string, password: string) => Promise<User>;
  * In that case, no cookies are set and no auth event is emitted.
  *
  * @throws {AuthError} On duplicate email, validation failure, network error, or missing Netlify runtime.
+ *
+ * @remarks
+ * **Server-side CSRF:** When called from a server endpoint, the endpoint must have CSRF
+ * protection. If your framework does not check the request's `Origin` by default, call
+ * {@link verifyRequestOrigin} at the start of the handler before invoking `signup()`.
  */
 declare const signup: (email: string, password: string, data?: SignupData) => Promise<User>;
 /**
@@ -286,6 +313,11 @@ declare const signup: (email: string, password: string, data?: SignupData) => Pr
  * invalidation request fails. In the browser, emits a `'logout'` event via {@link onAuthChange}.
  *
  * @throws {AuthError} On missing Netlify runtime (server) or logout failure (browser).
+ *
+ * @remarks
+ * **Server-side CSRF:** When called from a server endpoint, the endpoint must have CSRF
+ * protection. If your framework does not check the request's `Origin` by default, call
+ * {@link verifyRequestOrigin} at the start of the handler before invoking `logout()`.
  */
 declare const logout: () => Promise<void>;
 /**
@@ -343,7 +375,7 @@ interface CallbackResult {
  */
 declare const handleAuthCallback: () => Promise<CallbackResult | null>;
 /**
- * Hydrates the browser-side gotrue-js session from server-set auth cookies.
+ * Hydrates the browser-side session from server-set auth cookies.
  * Call this on page load when using server-side login to enable browser
  * account operations (updateUser, verifyEmailChange, etc.).
  *
@@ -388,7 +420,7 @@ declare const refreshSession: () => Promise<string | null>;
  * Thrown by auth operations when something goes wrong: invalid credentials,
  * network failures, missing runtime context, etc.
  *
- * The `status` field contains the HTTP status code from GoTrue when available
+ * The `status` field contains the HTTP status code from the Identity API when available
  * (e.g., 401 for bad credentials, 422 for validation errors).
  * The `cause` field preserves the original error for debugging.
  *
@@ -405,7 +437,7 @@ declare const refreshSession: () => Promise<string | null>;
  */
 declare class AuthError extends Error {
     name: string;
-    /** HTTP status code from GoTrue, if the error originated from an API response. */
+    /** HTTP status code from the Identity API, if the error originated from an API response. */
     status?: number;
     cause?: unknown;
     constructor(message: string, status?: number, options?: {
@@ -414,7 +446,7 @@ declare class AuthError extends Error {
     static from(error: unknown): AuthError;
 }
 /**
- * Thrown when a function requires a gotrue-js client but Netlify Identity
+ * Thrown when a function requires the Identity client but Netlify Identity
  * is not configured (no endpoint URL could be discovered).
  *
  * This typically means the site does not have Identity enabled, or the app
@@ -425,6 +457,63 @@ declare class MissingIdentityError extends Error {
     constructor(message?: string);
 }
 
+/**
+ * Options for {@link verifyRequestOrigin}.
+ */
+interface VerifyRequestOriginOptions {
+    /**
+     * Origins that are allowed to make state-changing requests to this endpoint.
+     *
+     * If omitted, the request is only accepted from its own origin (the origin of `request.url`),
+     * which is the right default for sites whose login form and login endpoint live on the same origin.
+     *
+     * Pass an explicit list when you trust additional origins (for example, a separate frontend domain
+     * posting to an API on another domain). The list replaces the default, so it must include every
+     * origin you want to allow, including the request's own origin if applicable.
+     *
+     * Each value should be a full origin string with scheme and host: `'https://example.com'`.
+     */
+    allowedOrigins?: string[];
+}
+/**
+ * Same-origin check for state-changing requests, can be used to defend against Cross-Site Request
+ * Forgery (CSRF) on server-side endpoints that call {@link login}, {@link signup}, or {@link logout}.
+ *
+ * Compares the incoming request's `Origin` header against the request's own origin (or an explicit
+ * allowlist via `options.allowedOrigins`) and throws if they don't match. Call this at the start of
+ * any server-side handler that performs an auth mutation, before invoking the auth function.
+ *
+ * The check runs unconditionally on every call: any HTTP method, with or without an `Origin` header.
+ * If you don't want the check to apply to a given method or path, simply don't call the helper there.
+ *
+ * @throws {AuthError} with status `403` when the request has no `Origin` header.
+ * @throws {AuthError} with status `403` when the request's `Origin` is not in the allowed origins.
+ *
+ * @example
+ * ```ts
+ * // Netlify Function
+ * 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' } })
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Allow a separate trusted origin (e.g. a marketing site posting to an app domain).
+ * // The list replaces the default, so include the request's own origin if you still want it allowed.
+ * verifyRequestOrigin(request, {
+ *   allowedOrigins: ['https://app.example.com', 'https://www.example.com'],
+ * })
+ * ```
+ */
+declare const verifyRequestOrigin: (request: Request, options?: VerifyRequestOriginOptions) => void;
+
 /**
  * The admin namespace for privileged user management operations.
  * All methods are server-only and require the operator token
@@ -436,7 +525,7 @@ interface Admin {
     /**
      * Lists all users. Server-only.
      *
-     * Calls GoTrue `GET /admin/users` with the operator token. Pagination
+     * Calls `GET /admin/users` with the operator token. Pagination
      * options (`page`, `perPage`) are forwarded as query parameters.
      *
      * @throws {AuthError} If called from a browser, or if the operator token is missing.
@@ -445,7 +534,7 @@ interface Admin {
     /**
      * Gets a single user by ID. Server-only.
      *
-     * Calls GoTrue `GET /admin/users/:id` with the operator token.
+     * Calls `GET /admin/users/:id` with the operator token.
      *
      * @throws {AuthError} If called from a browser, the user is not found,
      *   or the operator token is missing.
@@ -455,12 +544,12 @@ interface Admin {
      * Creates a new user. The user is auto-confirmed (no confirmation email is sent).
      * Server-only.
      *
-     * The optional `data` fields are forwarded as top-level attributes in the GoTrue
-     * request body. Accepted fields: `role`, `aud`, `app_metadata`, `user_metadata`.
+     * The optional `data` fields are forwarded as top-level attributes in the Identity API
+     * request body. Accepted fields: `role`, `app_metadata`, `user_metadata`.
      * Any other keys in `data` are silently ignored. `data` cannot override `email`,
      * `password`, or `confirm`.
      *
-     * Calls GoTrue `POST /admin/users` with the operator token.
+     * Calls `POST /admin/users` with the operator token.
      *
      * @throws {AuthError} If called from a browser, the email already exists,
      *   or the operator token is missing.
@@ -469,7 +558,7 @@ interface Admin {
     /**
      * Updates an existing user by ID. Server-only.
      *
-     * Calls GoTrue `PUT /admin/users/:id` with the operator token.
+     * Calls `PUT /admin/users/:id` with the operator token.
      *
      * @throws {AuthError} If called from a browser, the user is not found,
      *   the update fails, or the operator token is missing.
@@ -478,7 +567,7 @@ interface Admin {
     /**
      * Deletes a user by ID. Server-only.
      *
-     * Calls GoTrue `DELETE /admin/users/:id` with the operator token.
+     * Calls `DELETE /admin/users/:id` with the operator token.
      *
      * @throws {AuthError} If called from a browser, the user is not found,
      *   the deletion fails, or the operator token is missing.
@@ -528,4 +617,4 @@ declare const verifyEmailChange: (token: string) => Promise<User>;
  */
 declare const updateUser: (updates: UserUpdates) => Promise<User>;
 
-export { AUTH_EVENTS, type Admin, type AdminUserUpdates, type AppMetadata, type AuthCallback, AuthError, type AuthEvent, type AuthProvider, type CallbackResult, type CreateUserParams, type IdentityConfig, type ListUsersOptions, MissingIdentityError, type Settings, type SignupData, type User, type UserUpdates, acceptInvite, admin, confirmEmail, getIdentityConfig, getSettings, getUser, handleAuthCallback, hydrateSession, isAuthenticated, login, logout, oauthLogin, onAuthChange, recoverPassword, refreshSession, requestPasswordRecovery, signup, updateUser, verifyEmailChange };
+export { AUTH_EVENTS, type Admin, type AdminUserUpdates, type AppMetadata, type AuthCallback, AuthError, type AuthEvent, type AuthProvider, type CallbackResult, type CreateUserParams, type IdentityConfig, type ListUsersOptions, MissingIdentityError, type Settings, type SignupData, type User, type UserUpdates, type VerifyRequestOriginOptions, acceptInvite, admin, confirmEmail, getIdentityConfig, getSettings, getUser, handleAuthCallback, hydrateSession, isAuthenticated, login, logout, oauthLogin, onAuthChange, recoverPassword, refreshSession, requestPasswordRecovery, signup, updateUser, verifyEmailChange, verifyRequestOrigin };