@depup/supabase__auth-js 2.103.0-depup.0 → 2.110.8-depup.0

package/src/lib/types.ts

@@ -6,6 +6,12 @@ import {
   ServerCredentialCreationOptions,
   ServerCredentialRequestOptions,
   WebAuthnApi,
+  WebAuthnError,
+} from './webauthn'
+import type {
+  RegistrationResponseJSON,
+  AuthenticationResponseJSON,
+  ServerCredentialResponse,
 } from './webauthn'
 import {
   AuthenticationCredential,
@@ -120,12 +126,17 @@ export type GoTrueClientOptions = {
   /* If debug messages are emitted. Can be used to inspect the behavior of the library. If set to a function, the provided function will be used instead of `console.log()` to perform the logging. */
   debug?: boolean | ((message: string, ...args: any[]) => void)
   /**
-   * Provide your own locking mechanism based on the environment. By default,
-   * `navigatorLock` (Web Locks API) is used in browser environments when
-   * `persistSession` is true. Falls back to an in-process lock for non-browser
-   * environments (e.g. React Native).
+   * Provide your own locking mechanism based on the environment. By default
+   * the client coordinates refreshes itself (single-flight via
+   * `refreshingDeferred` + commit guard) and relies on the GoTrue server to
+   * resolve cross-tab refresh races. Passing a custom lock opts into a
+   * legacy path that wraps every auth operation in your supplied lock — this
+   * path is preserved for backwards compatibility (typically React Native
+   * `processLock` or Node multi-process setups).
    *
-   * @experimental
+   * @deprecated Custom locks still work in v2.x for backwards compatibility.
+   * The legacy lock path will be removed in v3 — drop this option from your
+   * constructor options before upgrading.
    */
   lock?: LockFunc
   /**
@@ -139,30 +150,14 @@ export type GoTrueClientOptions = {
    */
   throwOnError?: boolean
   /**
-   * The maximum time in milliseconds to wait for acquiring a cross-tab synchronization lock.
-   *
-   * When multiple browser tabs or windows use the auth client simultaneously, they coordinate
-   * via the Web Locks API to prevent race conditions during session refresh and other operations.
-   * This timeout controls how long to wait before attempting lock recovery.
-   *
-   * - **Positive value**: Wait up to this many milliseconds. If the lock is still held, attempt
-   *   automatic recovery by stealing it (the previous holder is evicted, its callback continues
-   *   to completion without exclusive access). This recovers from orphaned locks caused by
-   *   React Strict Mode double-mount, storage API hangs, or aborted operations.
-   * - **Zero (0)**: Fail immediately if the lock is unavailable; throws `LockAcquireTimeoutError`
-   *   (check `error.isAcquireTimeout === true`).
-   * - **Negative value**: Wait indefinitely — can cause permanent deadlocks if the lock is orphaned.
+   * The maximum time in milliseconds to wait for acquiring the custom lock
+   * supplied via the `lock` option. Only consulted when a custom `lock` is
+   * passed — the default lockless path doesn't use this timeout.
    *
    * @default 5000
    *
-   * @example
-   * ```ts
-   * const client = createClient(url, key, {
-   *   auth: {
-   *     lockAcquireTimeout: 5000, // 5 seconds, then steal orphaned lock
-   *   },
-   * })
-   * ```
+   * @deprecated Only used by the legacy lock path. Will be removed in v3
+   * along with the `lock` option.
    */
   lockAcquireTimeout?: number
 
@@ -174,6 +169,27 @@ export type GoTrueClientOptions = {
    * @default false
    */
   skipAutoInitialize?: boolean
+
+  /**
+   * Opt-in flags for experimental features. These APIs may change without
+   * notice and are disabled by default.
+   *
+   * @experimental
+   */
+  experimental?: ExperimentalFeatureFlags
+}
+
+export type ExperimentalFeatureFlags = {
+  /**
+   * Enables passkey support:
+   *   - `auth.signInWithPasskey()`, `auth.registerPasskey()`
+   *   - `auth.passkey.*`
+   *   - `auth.admin.passkey.*`
+   *
+   * Defaults to `false`. Calling any passkey method while this flag is
+   * disabled throws a descriptive error at call time.
+   */
+  passkey?: boolean
 }
 
 const WeakPasswordReasons = ['length', 'characters', 'pwned'] as const
@@ -212,7 +228,7 @@ export type RequestResult<T, ErrorType extends Error = AuthError> =
 
 /**
  * similar to RequestResult except it allows you to destructure the possible shape of the success response
- *  {@see RequestResult}
+ *  {@link RequestResult}
  */
 export type RequestResultSafeDestructure<T> =
   | { data: T; error: null }
@@ -235,7 +251,7 @@ export type AuthResponsePassword = RequestResultSafeDestructure<{
 /**
  * AuthOtpResponse is returned when OTP is used.
  *
- * {@see AuthResponse}
+ * {@link AuthResponse}
  */
 export type AuthOtpResponse = RequestResultSafeDestructure<{
   user: null
@@ -391,7 +407,7 @@ type FactorVerificationStatus = (typeof FactorVerificationStatuses)[number]
  *
  * @see {@link GoTrueMFAApi#enroll}
  * @see {@link GoTrueMFAApi#listFactors}
- * @see {@link GoTrueMFAAdminApi#listFactors}
+ * @see {@link GoTrueAdminMFAApi#listFactors}
  */
 export type Factor<
   Type extends FactorType = FactorType,
@@ -609,16 +625,14 @@ export type SignInAnonymouslyCredentials = {
   }
 }
 
-export type SignUpWithPasswordCredentials = Prettify<
-  PasswordCredentialsBase & {
-    options?: {
-      emailRedirectTo?: string // only for email
-      data?: object
-      captchaToken?: string
-      channel?: 'sms' | 'whatsapp' // only for phone
-    }
+export type SignUpWithPasswordCredentials = PasswordCredentialsBase & {
+  options?: {
+    emailRedirectTo?: string // only for email
+    data?: object
+    captchaToken?: string
+    channel?: 'sms' | 'whatsapp' // only for phone
   }
->
+}
 
 type PasswordCredentialsBase =
   | { email: string; password: string }
@@ -668,7 +682,7 @@ export type SignInWithPasswordlessCredentials =
       }
     }
 
-export type AuthFlowType = 'implicit' | 'pkce'
+export type AuthFlowType = 'implicit' | 'pkce' | (string & {})
 export type SignInWithOAuthCredentials = {
   /** One of the providers supported by GoTrue. */
   provider: Provider
@@ -833,8 +847,15 @@ export interface VerifyTokenHashParams {
   type: EmailOtpType
 }
 
-export type MobileOtpType = 'sms' | 'phone_change'
-export type EmailOtpType = 'signup' | 'invite' | 'magiclink' | 'recovery' | 'email_change' | 'email'
+export type MobileOtpType = 'sms' | 'phone_change' | (string & {})
+export type EmailOtpType =
+  | 'signup'
+  | 'invite'
+  | 'magiclink'
+  | 'recovery'
+  | 'email_change'
+  | 'email'
+  | (string & {})
 
 export type ResendParams =
   | {
@@ -995,11 +1016,11 @@ type MFAVerifyTOTPParamFields = {
   code: string
 }
 
-export type MFAVerifyTOTPParams = Prettify<MFAVerifyParamsBase & MFAVerifyTOTPParamFields>
+export type MFAVerifyTOTPParams = MFAVerifyParamsBase & MFAVerifyTOTPParamFields
 
 type MFAVerifyPhoneParamFields = MFAVerifyTOTPParamFields
 
-export type MFAVerifyPhoneParams = Prettify<MFAVerifyParamsBase & MFAVerifyPhoneParamFields>
+export type MFAVerifyPhoneParams = MFAVerifyParamsBase & MFAVerifyPhoneParamFields
 
 type MFAVerifyWebauthnParamFieldsBase = {
   /** Relying party ID */
@@ -1032,7 +1053,7 @@ export type MFAVerifyWebauthnParamFields<T extends 'create' | 'request' = 'creat
  * @see {@link https://w3c.github.io/webauthn/#sctn-verifying-assertion W3C WebAuthn Spec - Verifying an Authentication Assertion}
  */
 export type MFAVerifyWebauthnParams<T extends 'create' | 'request' = 'create' | 'request'> =
-  Prettify<MFAVerifyParamsBase & MFAVerifyWebauthnParamFields<T>>
+  MFAVerifyParamsBase & MFAVerifyWebauthnParamFields<T>
 
 export type MFAVerifyParams = MFAVerifyTOTPParams | MFAVerifyPhoneParams | MFAVerifyWebauthnParams
 
@@ -1044,16 +1065,14 @@ type MFAChallengeParamsBase = {
 const MFATOTPChannels = ['sms', 'whatsapp'] as const
 export type MFATOTPChannel = (typeof MFATOTPChannels)[number]
 
-export type MFAChallengeTOTPParams = Prettify<MFAChallengeParamsBase>
+export type MFAChallengeTOTPParams = MFAChallengeParamsBase
 
 type MFAChallengePhoneParamFields<Channel extends MFATOTPChannel = MFATOTPChannel> = {
   /** Messaging channel to use (e.g. whatsapp or sms). Only relevant for phone factors */
   channel: Channel
 }
 
-export type MFAChallengePhoneParams = Prettify<
-  MFAChallengeParamsBase & MFAChallengePhoneParamFields
->
+export type MFAChallengePhoneParams = MFAChallengeParamsBase & MFAChallengePhoneParamFields
 
 /** WebAuthn parameters for WebAuthn factor challenge */
 type MFAChallengeWebauthnParamFields = {
@@ -1070,9 +1089,7 @@ type MFAChallengeWebauthnParamFields = {
  * Includes Relying Party information needed for WebAuthn ceremonies.
  * @see {@link https://w3c.github.io/webauthn/#sctn-rp-operations W3C WebAuthn Spec - Relying Party Operations}
  */
-export type MFAChallengeWebauthnParams = Prettify<
-  MFAChallengeParamsBase & MFAChallengeWebauthnParamFields
->
+export type MFAChallengeWebauthnParams = MFAChallengeParamsBase & MFAChallengeWebauthnParamFields
 
 export type MFAChallengeParams =
   | MFAChallengeTOTPParams
@@ -1083,9 +1100,8 @@ type MFAChallengeAndVerifyParamsBase = Omit<MFAVerifyParamsBase, 'challengeId'>
 
 type MFAChallengeAndVerifyTOTPParamFields = MFAVerifyTOTPParamFields
 
-type MFAChallengeAndVerifyTOTPParams = Prettify<
-  MFAChallengeAndVerifyParamsBase & MFAChallengeAndVerifyTOTPParamFields
->
+type MFAChallengeAndVerifyTOTPParams = MFAChallengeAndVerifyParamsBase &
+  MFAChallengeAndVerifyTOTPParamFields
 
 export type MFAChallengeAndVerifyParams = MFAChallengeAndVerifyTOTPParams
 
@@ -1142,7 +1158,7 @@ type AuthMFAChallengeTOTPResponseFields = {
 }
 
 export type AuthMFAChallengeTOTPResponse = RequestResult<
-  Prettify<AuthMFAChallengeResponseBase<'totp'> & AuthMFAChallengeTOTPResponseFields>
+  AuthMFAChallengeResponseBase<'totp'> & AuthMFAChallengeTOTPResponseFields
 >
 
 type AuthMFAChallengePhoneResponseFields = {
@@ -1150,7 +1166,7 @@ type AuthMFAChallengePhoneResponseFields = {
 }
 
 export type AuthMFAChallengePhoneResponse = RequestResult<
-  Prettify<AuthMFAChallengeResponseBase<'phone'> & AuthMFAChallengePhoneResponseFields>
+  AuthMFAChallengeResponseBase<'phone'> & AuthMFAChallengePhoneResponseFields
 >
 
 type AuthMFAChallengeWebauthnResponseFields = {
@@ -1171,7 +1187,7 @@ type AuthMFAChallengeWebauthnResponseFields = {
  * @see {@link https://w3c.github.io/webauthn/#sctn-credential-creation W3C WebAuthn Spec - Credential Creation}
  */
 export type AuthMFAChallengeWebauthnResponse = RequestResult<
-  Prettify<AuthMFAChallengeResponseBase<'webauthn'> & AuthMFAChallengeWebauthnResponseFields>
+  AuthMFAChallengeResponseBase<'webauthn'> & AuthMFAChallengeWebauthnResponseFields
 >
 
 type AuthMFAChallengeWebauthnResponseFieldsJSON = {
@@ -1190,9 +1206,8 @@ type AuthMFAChallengeWebauthnResponseFieldsJSON = {
  * JSON-serializable version of WebAuthn challenge response.
  * Used for server communication with base64url-encoded binary fields.
  */
-export type AuthMFAChallengeWebauthnResponseDataJSON = Prettify<
-  AuthMFAChallengeResponseBase<'webauthn'> & AuthMFAChallengeWebauthnResponseFieldsJSON
->
+export type AuthMFAChallengeWebauthnResponseDataJSON = AuthMFAChallengeResponseBase<'webauthn'> &
+  AuthMFAChallengeWebauthnResponseFieldsJSON
 
 /**
  * Server response type for WebAuthn MFA challenge.
@@ -1211,15 +1226,15 @@ export type AuthMFAListFactorsResponse<T extends typeof FactorTypes = typeof Fac
   RequestResult<
     {
       /** All available factors (verified and unverified). */
-      all: Prettify<Factor>[]
+      all: Factor[]
 
       // Dynamically create a property for each factor type with only verified factors
     } & {
-      [K in T[number]]: Prettify<Factor<K, 'verified'>>[]
+      [K in T[number]]: Factor<K, 'verified'>[]
     }
   >
 
-export type AuthenticatorAssuranceLevels = 'aal1' | 'aal2'
+export type AuthenticatorAssuranceLevels = 'aal1' | 'aal2' | (string & {})
 
 export type AuthMFAGetAuthenticatorAssuranceLevelResponse = RequestResult<{
   /** Current AAL level of the session. */
@@ -1260,6 +1275,7 @@ export interface GoTrueMFAApi {
    * Upon verifying a factor, all other sessions are logged out and the current session's authenticator level is promoted to `aal2`.
    *
    * @category Auth
+   * @subcategory Auth MFA
    *
    * @remarks
    * - Use `totp` or `phone` as the `factorType` and use the returned `id` to create a challenge.
@@ -1340,6 +1356,7 @@ export interface GoTrueMFAApi {
    * factor.
    *
    * @category Auth
+   * @subcategory Auth MFA
    *
    * @remarks
    * - An [enrolled factor](/docs/reference/javascript/auth-mfa-enroll) is required before creating a challenge.
@@ -1413,6 +1430,7 @@ export interface GoTrueMFAApi {
    * provided by the user by entering a code seen in their authenticator app.
    *
    * @category Auth
+   * @subcategory Auth MFA
    *
    * @remarks
    * - To verify a challenge, please [create a challenge](/docs/reference/javascript/auth-mfa-challenge) first.
@@ -1496,6 +1514,7 @@ export interface GoTrueMFAApi {
    * A user has to have an `aal2` authenticator level in order to unenroll a `verified` factor.
    *
    * @category Auth
+   * @subcategory Auth MFA
    *
    * @example Unenroll a factor
    * ```js
@@ -1521,6 +1540,7 @@ export interface GoTrueMFAApi {
    * provided by the user by entering a code seen in their authenticator app.
    *
    * @category Auth
+   * @subcategory Auth MFA
    *
    * @remarks
    * - Intended for use with only TOTP factors.
@@ -1606,6 +1626,7 @@ export interface GoTrueMFAApi {
    *
    *
    * @category Auth
+   * @subcategory Auth MFA
    */
   listFactors(): Promise<AuthMFAListFactorsResponse>
 
@@ -1625,6 +1646,7 @@ export interface GoTrueMFAApi {
    * @param jwt Takes in an optional access token JWT. If no JWT is provided, the JWT from the current session is used.
    *
    * @category Auth
+   * @subcategory Auth MFA
    *
    * @remarks
    * - Authenticator Assurance Level (AAL) is the measure of the strength of an authentication mechanism.
@@ -1669,14 +1691,14 @@ export interface GoTrueMFAApi {
 }
 
 /**
- * @expermental
+ * @experimental
  */
 export type AuthMFAAdminDeleteFactorResponse = RequestResult<{
   /** ID of the factor that was successfully deleted. */
   id: string
 }>
 /**
- * @expermental
+ * @experimental
  */
 export type AuthMFAAdminDeleteFactorParams = {
   /** ID of the MFA factor to delete. */
@@ -1687,7 +1709,7 @@ export type AuthMFAAdminDeleteFactorParams = {
 }
 
 /**
- * @expermental
+ * @experimental
  */
 export type AuthMFAAdminListFactorsResponse = RequestResult<{
   /** All factors attached to the user. */
@@ -1695,7 +1717,7 @@ export type AuthMFAAdminListFactorsResponse = RequestResult<{
 }>
 
 /**
- * @expermental
+ * @experimental
  */
 export type AuthMFAAdminListFactorsParams = {
   /** ID of the user. */
@@ -1705,7 +1727,7 @@ export type AuthMFAAdminListFactorsParams = {
 /**
  * Contains the full multi-factor authentication administration API.
  *
- * @expermental
+ * @experimental
  */
 export interface GoTrueAdminMFAApi {
   /**
@@ -1713,6 +1735,7 @@ export interface GoTrueAdminMFAApi {
    *
    *
    * @category Auth
+   * @subcategory Auth Admin
    *
    * @example List all factors for a user
    * ```js
@@ -1746,9 +1769,10 @@ export interface GoTrueAdminMFAApi {
    *
    * @see {@link GoTrueMFAApi#unenroll}
    *
-   * @expermental
+   * @experimental
    *
    * @category Auth
+   * @subcategory Auth Admin
    *
    * @example Delete a factor for a user
    * ```js
@@ -1837,15 +1861,13 @@ type MFAEnrollTOTPParamFields = {
   issuer?: string
 }
 
-export type MFAEnrollTOTPParams = Prettify<MFAEnrollParamsBase<'totp'> & MFAEnrollTOTPParamFields>
+export type MFAEnrollTOTPParams = MFAEnrollParamsBase<'totp'> & MFAEnrollTOTPParamFields
 
 type MFAEnrollPhoneParamFields = {
   /** Phone number associated with a factor. Number should conform to E.164 format */
   phone: string
 }
-export type MFAEnrollPhoneParams = Prettify<
-  MFAEnrollParamsBase<'phone'> & MFAEnrollPhoneParamFields
->
+export type MFAEnrollPhoneParams = MFAEnrollParamsBase<'phone'> & MFAEnrollPhoneParamFields
 
 type MFAEnrollWebauthnFields = {
   /** no extra fields for now, kept for consistency and for possible future changes  */
@@ -1856,9 +1878,7 @@ type MFAEnrollWebauthnFields = {
  * Creates an unverified WebAuthn factor that must be verified with a credential.
  * @see {@link https://w3c.github.io/webauthn/#sctn-registering-a-new-credential W3C WebAuthn Spec - Registering a New Credential}
  */
-export type MFAEnrollWebauthnParams = Prettify<
-  MFAEnrollParamsBase<'webauthn'> & MFAEnrollWebauthnFields
->
+export type MFAEnrollWebauthnParams = MFAEnrollParamsBase<'webauthn'> & MFAEnrollWebauthnFields
 
 type AuthMFAEnrollResponseBase<T extends FactorType> = {
   /** ID of the factor that was just enrolled (in an unverified state). */
@@ -1891,7 +1911,7 @@ type AuthMFAEnrollTOTPResponseFields = {
 }
 
 export type AuthMFAEnrollTOTPResponse = RequestResult<
-  Prettify<AuthMFAEnrollResponseBase<'totp'> & AuthMFAEnrollTOTPResponseFields>
+  AuthMFAEnrollResponseBase<'totp'> & AuthMFAEnrollTOTPResponseFields
 >
 
 type AuthMFAEnrollPhoneResponseFields = {
@@ -1900,7 +1920,7 @@ type AuthMFAEnrollPhoneResponseFields = {
 }
 
 export type AuthMFAEnrollPhoneResponse = RequestResult<
-  Prettify<AuthMFAEnrollResponseBase<'phone'> & AuthMFAEnrollPhoneResponseFields>
+  AuthMFAEnrollResponseBase<'phone'> & AuthMFAEnrollPhoneResponseFields
 >
 
 type AuthMFAEnrollWebauthnFields = {
@@ -1913,11 +1933,11 @@ type AuthMFAEnrollWebauthnFields = {
  * @see {@link https://w3c.github.io/webauthn/#sctn-registering-a-new-credential W3C WebAuthn Spec - Registering a New Credential}
  */
 export type AuthMFAEnrollWebauthnResponse = RequestResult<
-  Prettify<AuthMFAEnrollResponseBase<'webauthn'> & AuthMFAEnrollWebauthnFields>
+  AuthMFAEnrollResponseBase<'webauthn'> & AuthMFAEnrollWebauthnFields
 >
 
 export type JwtHeader = {
-  alg: 'RS256' | 'ES256' | 'HS256'
+  alg: 'RS256' | 'ES256' | 'HS256' | (string & {})
   kid: string
   typ: string
 }
@@ -1968,7 +1988,7 @@ export interface JwtPayload extends RequiredClaims {
 }
 
 export interface JWK {
-  kty: 'RSA' | 'EC' | 'oct'
+  kty: 'RSA' | 'EC' | 'oct' | (string & {})
   key_ops: string[]
   alg?: string
   kid?: string
@@ -1982,7 +2002,7 @@ export type SignOutScope = (typeof SIGN_OUT_SCOPES)[number]
  * OAuth client grant types supported by the OAuth 2.1 server.
  * Only relevant when the OAuth 2.1 server is enabled in Supabase Auth.
  */
-export type OAuthClientGrantType = 'authorization_code' | 'refresh_token'
+export type OAuthClientGrantType = 'authorization_code' | 'refresh_token' | (string & {})
 
 /**
  * OAuth client response types supported by the OAuth 2.1 server.
@@ -2119,6 +2139,7 @@ export interface GoTrueAdminOAuthApi {
    * This function should only be called on a server. Never expose your `service_role` key in the browser.
    *
    * @category Auth
+   * @subcategory OAuth Admin
    */
   listClients(params?: PageParams): Promise<OAuthClientListResponse>
 
@@ -2129,6 +2150,7 @@ export interface GoTrueAdminOAuthApi {
    * This function should only be called on a server. Never expose your `service_role` key in the browser.
    *
    * @category Auth
+   * @subcategory OAuth Admin
    */
   createClient(params: CreateOAuthClientParams): Promise<OAuthClientResponse>
 
@@ -2139,6 +2161,7 @@ export interface GoTrueAdminOAuthApi {
    * This function should only be called on a server. Never expose your `service_role` key in the browser.
    *
    * @category Auth
+   * @subcategory OAuth Admin
    */
   getClient(clientId: string): Promise<OAuthClientResponse>
 
@@ -2149,6 +2172,7 @@ export interface GoTrueAdminOAuthApi {
    * This function should only be called on a server. Never expose your `service_role` key in the browser.
    *
    * @category Auth
+   * @subcategory OAuth Admin
    */
   updateClient(clientId: string, params: UpdateOAuthClientParams): Promise<OAuthClientResponse>
 
@@ -2159,6 +2183,7 @@ export interface GoTrueAdminOAuthApi {
    * This function should only be called on a server. Never expose your `service_role` key in the browser.
    *
    * @category Auth
+   * @subcategory OAuth Admin
    */
   deleteClient(clientId: string): Promise<{ data: null; error: AuthError | null }>
 
@@ -2169,6 +2194,7 @@ export interface GoTrueAdminOAuthApi {
    * This function should only be called on a server. Never expose your `service_role` key in the browser.
    *
    * @category Auth
+   * @subcategory OAuth Admin
    */
   regenerateClientSecret(clientId: string): Promise<OAuthClientResponse>
 }
@@ -2224,6 +2250,14 @@ export type CustomOAuthProvider = {
   acceptable_client_ids?: string[]
   /** OAuth scopes requested during authorization */
   scopes?: string[]
+  /**
+   * Allowlist of raw identity provider claim keys to copy verbatim into the
+   * user's `custom_claims` field (within `identity_data` and
+   * `raw_user_meta_data`), e.g. `["groups", "org_id", "mail"]`. This is an
+   * opt-in allowlist that defaults to empty (no claims captured) and operates
+   * independently from `attribute_mapping`.
+   */
+  custom_claims_allowlist?: string[]
   /** Whether PKCE is enabled */
   pkce_enabled?: boolean
   /** Mapping of provider attributes to Supabase user attributes */
@@ -2274,6 +2308,14 @@ export type CreateCustomProviderParams = {
   acceptable_client_ids?: string[]
   /** OAuth scopes requested during authorization */
   scopes?: string[]
+  /**
+   * Allowlist of raw identity provider claim keys to copy verbatim into the
+   * user's `custom_claims` field (within `identity_data` and
+   * `raw_user_meta_data`), e.g. `["groups", "org_id", "mail"]`. This is an
+   * opt-in allowlist that defaults to empty (no claims captured) and operates
+   * independently from `attribute_mapping`.
+   */
+  custom_claims_allowlist?: string[]
   /** Whether PKCE is enabled */
   pkce_enabled?: boolean
   /** Mapping of provider attributes to Supabase user attributes */
@@ -2316,6 +2358,14 @@ export type UpdateCustomProviderParams = {
   acceptable_client_ids?: string[]
   /** OAuth scopes requested during authorization */
   scopes?: string[]
+  /**
+   * Allowlist of raw identity provider claim keys to copy verbatim into the
+   * user's `custom_claims` field (within `identity_data` and
+   * `raw_user_meta_data`), e.g. `["groups", "org_id", "mail"]`. This is an
+   * opt-in allowlist that defaults to empty (no claims captured) and operates
+   * independently from `attribute_mapping`.
+   */
+  custom_claims_allowlist?: string[]
   /** Whether PKCE is enabled */
   pkce_enabled?: boolean
   /** Mapping of provider attributes to Supabase user attributes */
@@ -2376,6 +2426,9 @@ export interface GoTrueAdminCustomProvidersApi {
    * Lists all custom providers with optional type filter.
    *
    * This function should only be called on a server. Never expose your `service_role` key in the browser.
+   *
+   * @category Auth
+   * @subcategory Auth Admin
    */
   listProviders(params?: ListCustomProvidersParams): Promise<CustomProviderListResponse>
 
@@ -2389,6 +2442,9 @@ export interface GoTrueAdminCustomProvidersApi {
    * in the document does not match the expected issuer.
    *
    * This function should only be called on a server. Never expose your `service_role` key in the browser.
+   *
+   * @category Auth
+   * @subcategory Auth Admin
    */
   createProvider(params: CreateCustomProviderParams): Promise<CustomProviderResponse>
 
@@ -2396,6 +2452,9 @@ export interface GoTrueAdminCustomProvidersApi {
    * Gets details of a specific custom provider by identifier.
    *
    * This function should only be called on a server. Never expose your `service_role` key in the browser.
+   *
+   * @category Auth
+   * @subcategory Auth Admin
    */
   getProvider(identifier: string): Promise<CustomProviderResponse>
 
@@ -2408,6 +2467,9 @@ export interface GoTrueAdminCustomProvidersApi {
    * the issuer does not match.
    *
    * This function should only be called on a server. Never expose your `service_role` key in the browser.
+   *
+   * @category Auth
+   * @subcategory Auth Admin
    */
   updateProvider(
     identifier: string,
@@ -2418,6 +2480,9 @@ export interface GoTrueAdminCustomProvidersApi {
    * Deletes a custom provider.
    *
    * This function should only be called on a server. Never expose your `service_role` key in the browser.
+   *
+   * @category Auth
+   * @subcategory Auth Admin
    */
   deleteProvider(identifier: string): Promise<{ data: null; error: AuthError | null }>
 }
@@ -2570,6 +2635,7 @@ export interface AuthOAuthServerApi {
    * @returns Authorization details or redirect URL depending on consent status
    *
    * @category Auth
+   * @subcategory OAuth Server
    */
   getAuthorizationDetails(authorizationId: string): Promise<AuthOAuthAuthorizationDetailsResponse>
 
@@ -2586,6 +2652,7 @@ export interface AuthOAuthServerApi {
    * @returns Redirect URL to send the user back to the OAuth client with authorization code
    *
    * @category Auth
+   * @subcategory OAuth Server
    */
   approveAuthorization(
     authorizationId: string,
@@ -2605,6 +2672,7 @@ export interface AuthOAuthServerApi {
    * @returns Redirect URL to send the user back to the OAuth client with error information
    *
    * @category Auth
+   * @subcategory OAuth Server
    */
   denyAuthorization(
     authorizationId: string,
@@ -2618,6 +2686,7 @@ export interface AuthOAuthServerApi {
    * @returns Response with array of OAuth grants with client information and granted scopes
    *
    * @category Auth
+   * @subcategory OAuth Server
    */
   listGrants(): Promise<AuthOAuthGrantsResponse>
 
@@ -2633,6 +2702,229 @@ export interface AuthOAuthServerApi {
    * @returns Empty response on successful revocation
    *
    * @category Auth
+   * @subcategory OAuth Server
    */
   revokeGrant(options: { clientId: string }): Promise<AuthOAuthRevokeGrantResponse>
 }
+
+// --- Passkey Types ---
+
+/** Response from POST /passkeys/registration/options */
+export type PasskeyRegistrationOptionsResponse = {
+  challenge_id: string
+  options: ServerCredentialCreationOptions
+  expires_at: number
+}
+
+/** Request body for POST /passkeys/registration/verify */
+export type PasskeyRegistrationVerifyParams = {
+  challenge_id: string
+  credential: RegistrationResponseJSON
+}
+
+/** Response from POST /passkeys/registration/verify */
+export type PasskeyMetadata = {
+  id: string
+  friendly_name?: string
+  created_at: string
+}
+
+/** Response from POST /passkeys/authentication/options */
+export type PasskeyAuthenticationOptionsResponse = {
+  challenge_id: string
+  options: ServerCredentialRequestOptions
+  expires_at: number
+}
+
+/** Request body for POST /passkeys/authentication/verify */
+export type PasskeyAuthenticationVerifyParams = {
+  challenge_id: string
+  credential: AuthenticationResponseJSON
+}
+
+/** Item in the passkeys list (GET /passkeys/ and admin list) */
+export type PasskeyListItem = {
+  id: string
+  friendly_name?: string
+  created_at: string
+  last_used_at?: string
+}
+
+// --- Passkey SDK Method Parameter/Response Types ---
+
+export type SignInWithPasskeyCredentials = {
+  options?: {
+    captchaToken?: string
+    signal?: AbortSignal
+  }
+}
+
+export type RegisterPasskeyCredentials = {
+  options?: {
+    signal?: AbortSignal
+  }
+}
+
+export type VerifyPasskeyRegistrationParams = {
+  /** Challenge ID from startRegistration */
+  challengeId: string
+  /** Serialized credential from navigator.credentials.create() */
+  credential: ServerCredentialResponse
+}
+
+export type StartPasskeyAuthenticationParams = {
+  options?: {
+    captchaToken?: string
+  }
+}
+
+export type VerifyPasskeyAuthenticationParams = {
+  /** Challenge ID from startAuthentication */
+  challengeId: string
+  /** Serialized credential from navigator.credentials.get() */
+  credential: ServerCredentialResponse
+}
+
+export type PasskeyUpdateParams = {
+  /** UUID of the passkey to update */
+  passkeyId: string
+  /** New friendly name (max 120 chars) */
+  friendlyName: string
+}
+
+export type PasskeyDeleteParams = {
+  /** UUID of the passkey to delete */
+  passkeyId: string
+}
+
+// --- Passkey Response Types ---
+
+export type AuthPasskeyRegistrationOptionsResponse =
+  RequestResult<PasskeyRegistrationOptionsResponse>
+export type AuthPasskeyRegistrationVerifyResponse = RequestResult<
+  PasskeyMetadata,
+  WebAuthnError | AuthError
+>
+export type AuthPasskeyAuthenticationOptionsResponse =
+  RequestResult<PasskeyAuthenticationOptionsResponse>
+export type AuthPasskeyAuthenticationVerifyResponse = RequestResult<
+  { session: Session | null; user: User | null },
+  WebAuthnError | AuthError
+>
+export type AuthPasskeyListResponse = RequestResult<PasskeyListItem[]>
+export type AuthPasskeyUpdateResponse = RequestResult<PasskeyListItem>
+export type AuthPasskeyDeleteResponse = RequestResult<null>
+
+// --- Passkey Admin Types ---
+
+export type AuthPasskeyAdminListParams = {
+  userId: string
+}
+
+export type AuthPasskeyAdminDeleteParams = {
+  userId: string
+  passkeyId: string
+}
+
+// --- Passkey Namespace Interfaces ---
+
+/**
+ * Lower-level two-step API and management methods for passkeys.
+ * Access via `supabase.auth.passkey`.
+ */
+export interface AuthPasskeyApi {
+  // Two-step registration
+  /**
+   * Starts the passkey registration ceremony. Fetches a registration challenge
+   * and credential creation options from the server. Used as the first step of
+   * a two-step registration flow when the caller wants to handle
+   * `navigator.credentials.create()` themselves.
+   *
+   * @category Auth
+   * @subcategory Auth Passkey
+   */
+  startRegistration(): Promise<AuthPasskeyRegistrationOptionsResponse>
+
+  /**
+   * Verifies a passkey registration credential against a previously issued
+   * challenge. Used as the second step of a two-step registration flow.
+   *
+   * @category Auth
+   * @subcategory Auth Passkey
+   */
+  verifyRegistration(
+    params: VerifyPasskeyRegistrationParams
+  ): Promise<AuthPasskeyRegistrationVerifyResponse>
+
+  // Two-step authentication
+  /**
+   * Starts the passkey authentication ceremony. Fetches an authentication
+   * challenge and credential request options from the server. Used as the
+   * first step of a two-step sign-in flow when the caller wants to handle
+   * `navigator.credentials.get()` themselves.
+   *
+   * @category Auth
+   * @subcategory Auth Passkey
+   */
+  startAuthentication(
+    params?: StartPasskeyAuthenticationParams
+  ): Promise<AuthPasskeyAuthenticationOptionsResponse>
+
+  /**
+   * Verifies a passkey authentication credential against a previously issued
+   * challenge. Used as the second step of a two-step sign-in flow.
+   *
+   * @category Auth
+   * @subcategory Auth Passkey
+   */
+  verifyAuthentication(
+    params: VerifyPasskeyAuthenticationParams
+  ): Promise<AuthPasskeyAuthenticationVerifyResponse>
+
+  // Management
+  /**
+   * Lists all passkeys registered for the currently signed-in user.
+   *
+   * @category Auth
+   * @subcategory Auth Passkey
+   */
+  list(): Promise<AuthPasskeyListResponse>
+
+  /**
+   * Updates a passkey's friendly name.
+   *
+   * @category Auth
+   * @subcategory Auth Passkey
+   */
+  update(params: PasskeyUpdateParams): Promise<AuthPasskeyUpdateResponse>
+
+  /**
+   * Deletes a passkey for the currently signed-in user.
+   *
+   * @category Auth
+   * @subcategory Auth Passkey
+   */
+  delete(params: PasskeyDeleteParams): Promise<AuthPasskeyDeleteResponse>
+}
+
+export interface GoTrueAdminPasskeyApi {
+  /**
+   * Lists all passkeys registered for a specific user.
+   *
+   * This function should only be called on a server. Never expose your `service_role` key in the browser.
+   *
+   * @category Auth
+   * @subcategory Passkey Admin
+   */
+  listPasskeys(params: AuthPasskeyAdminListParams): Promise<AuthPasskeyListResponse>
+
+  /**
+   * Deletes a specific passkey for a specific user.
+   *
+   * This function should only be called on a server. Never expose your `service_role` key in the browser.
+   *
+   * @category Auth
+   * @subcategory Passkey Admin
+   */
+  deletePasskey(params: AuthPasskeyAdminDeleteParams): Promise<AuthPasskeyDeleteResponse>
+}