@supabase/auth-js 3.0.0-next.0 → 3.0.0-next.10

package/src/GoTrueClient.ts

@@ -33,6 +33,7 @@ import {
   _userResponse,
 } from './lib/fetch'
 import {
+  assertPasskeyExperimentalEnabled,
   decodeJWT,
   deepClone,
   Deferred,
@@ -136,6 +137,22 @@ import type {
   UserResponse,
   VerifyOtpParams,
   Web3Credentials,
+  AuthPasskeyApi,
+  ExperimentalFeatureFlags,
+  SignInWithPasskeyCredentials,
+  RegisterPasskeyCredentials,
+  VerifyPasskeyRegistrationParams,
+  StartPasskeyAuthenticationParams,
+  VerifyPasskeyAuthenticationParams,
+  PasskeyUpdateParams,
+  PasskeyDeleteParams,
+  AuthPasskeyRegistrationOptionsResponse,
+  AuthPasskeyRegistrationVerifyResponse,
+  AuthPasskeyAuthenticationOptionsResponse,
+  AuthPasskeyAuthenticationVerifyResponse,
+  AuthPasskeyListResponse,
+  AuthPasskeyUpdateResponse,
+  AuthPasskeyDeleteResponse,
 } from './lib/types'
 import {
   createSiweMessage,
@@ -146,10 +163,14 @@ import {
   toHex,
 } from './lib/web3/ethereum'
 import {
+  createCredential,
   deserializeCredentialCreationOptions,
   deserializeCredentialRequestOptions,
+  getCredential,
   serializeCredentialCreationResponse,
   serializeCredentialRequestResponse,
+  browserSupportsWebAuthn,
+  webAuthnAbortService,
   WebAuthnApi,
 } from './lib/webauthn'
 import {
@@ -176,6 +197,7 @@ const DEFAULT_OPTIONS: Omit<
   throwOnError: false,
   lockAcquireTimeout: 5000, // 5 seconds
   skipAutoInitialize: false,
+  experimental: {},
 }
 
 async function lockNoOp<R>(name: string, acquireTimeout: number, fn: () => Promise<R>): Promise<R> {
@@ -212,6 +234,13 @@ export default class GoTrueClient {
    * Used to implement the authorization code flow on the consent page.
    */
   oauth: AuthOAuthServerApi
+  /**
+   * Namespace for passkey methods.
+   * Includes lower-level two-step registration/authentication and passkey management.
+   *
+   * Requires `auth.experimental.passkey: true`; otherwise all methods throw.
+   */
+  passkey: AuthPasskeyApi
   /**
    * The storage key used to identify the values saved in localStorage
    */
@@ -273,6 +302,11 @@ export default class GoTrueClient {
   protected pendingInLock: Promise<any>[] = []
   protected throwOnError: boolean
   protected lockAcquireTimeout: number
+  /**
+   * Opt-in flags for experimental features. Defaults to an empty object.
+   * See `GoTrueClientOptions.experimental`.
+   */
+  protected experimental: ExperimentalFeatureFlags
 
   /**
    * Used to broadcast state change events to other tabs listening.
@@ -289,7 +323,7 @@ export default class GoTrueClient {
    * ```ts
    * import { createClient } from '@supabase/supabase-js'
    *
-   * const supabase = createClient('https://xyzcompany.supabase.co', 'publishable-or-anon-key')
+   * const supabase = createClient('https://xyzcompany.supabase.co', 'your-publishable-key')
    * const { data, error } = await supabase.auth.getUser()
    * ```
    *
@@ -299,7 +333,7 @@ export default class GoTrueClient {
    *
    * const auth = new GoTrueClient({
    *   url: 'https://xyzcompany.supabase.co/auth/v1',
-   *   headers: { apikey: 'publishable-or-anon-key' },
+   *   headers: { apikey: 'your-publishable-key' },
    *   storageKey: 'supabase-auth',
    * })
    * ```
@@ -326,10 +360,12 @@ export default class GoTrueClient {
 
     this.persistSession = settings.persistSession
     this.autoRefreshToken = settings.autoRefreshToken
+    this.experimental = settings.experimental ?? {}
     this.admin = new GoTrueAdminApi({
       url: settings.url,
       headers: settings.headers,
       fetch: settings.fetch,
+      experimental: this.experimental,
     })
 
     this.url = settings.url
@@ -374,6 +410,16 @@ export default class GoTrueClient {
       revokeGrant: this._revokeOAuthGrant.bind(this),
     }
 
+    this.passkey = {
+      startRegistration: this._startPasskeyRegistration.bind(this),
+      verifyRegistration: this._verifyPasskeyRegistration.bind(this),
+      startAuthentication: this._startPasskeyAuthentication.bind(this),
+      verifyAuthentication: this._verifyPasskeyAuthentication.bind(this),
+      list: this._listPasskeys.bind(this),
+      update: this._updatePasskey.bind(this),
+      delete: this._deletePasskey.bind(this),
+    }
+
     if (this.persistSession) {
       if (settings.storage) {
         this.storage = settings.storage
@@ -1835,7 +1881,10 @@ export default class GoTrueClient {
       }
       if (data.session) {
         await this._saveSession(data.session)
-        await this._notifyAllSubscribers('SIGNED_IN', data.session)
+        await this._notifyAllSubscribers(
+          redirectType === 'recovery' ? 'PASSWORD_RECOVERY' : 'SIGNED_IN',
+          data.session
+        )
       }
       return this._returnResult({ data: { ...data, redirectType: redirectType ?? null }, error })
     } catch (error) {
@@ -3584,7 +3633,10 @@ export default class GoTrueClient {
 
         window.history.replaceState(window.history.state, '', url.toString())
 
-        return { data: { session: data.session, redirectType: null }, error: null }
+        return {
+          data: { session: data.session, redirectType: data.redirectType ?? null },
+          error: null,
+        }
       }
 
       const {
@@ -5906,4 +5958,388 @@ export default class GoTrueClient {
       throw error
     }
   }
+
+  // --- Passkey Methods ---
+
+  /**
+   * Sign in with a passkey. Handles the full WebAuthn ceremony:
+   * 1. Fetches authentication challenge from server
+   * 2. Prompts user via navigator.credentials.get()
+   * 3. Verifies credential with server and creates session
+   *
+   * Requires `auth.experimental.passkey: true`.
+   */
+  async signInWithPasskey(
+    credentials?: SignInWithPasskeyCredentials
+  ): Promise<AuthPasskeyAuthenticationVerifyResponse> {
+    assertPasskeyExperimentalEnabled(this.experimental)
+    try {
+      if (!browserSupportsWebAuthn()) {
+        return this._returnResult({
+          data: null,
+          error: new AuthUnknownError('Browser does not support WebAuthn', null),
+        })
+      }
+
+      // 1. Get challenge options from server
+      const { data: options, error: optionsError } = await this._startPasskeyAuthentication({
+        options: { captchaToken: credentials?.options?.captchaToken },
+      })
+      if (optionsError || !options) {
+        return this._returnResult({ data: null, error: optionsError })
+      }
+
+      // 2. Deserialize and prompt user via browser WebAuthn API
+      const publicKeyOptions = deserializeCredentialRequestOptions(options.options)
+      const signal = credentials?.options?.signal ?? webAuthnAbortService.createNewAbortSignal()
+      const { data: credential, error: credentialError } = await getCredential({
+        publicKey: publicKeyOptions,
+        signal,
+      })
+      if (credentialError || !credential) {
+        return this._returnResult({
+          data: null,
+          error: credentialError ?? new AuthUnknownError('WebAuthn ceremony failed', null),
+        })
+      }
+
+      // 3. Serialize and verify with server
+      const serialized = serializeCredentialRequestResponse(credential)
+      return this._verifyPasskeyAuthentication({
+        challengeId: options.challenge_id,
+        credential: serialized,
+      })
+    } catch (error) {
+      if (isAuthError(error)) {
+        return this._returnResult({ data: null, error })
+      }
+      throw error
+    }
+  }
+
+  /**
+   * Register a passkey for the current authenticated user. Handles the full WebAuthn ceremony:
+   * 1. Fetches registration challenge from server
+   * 2. Prompts user via navigator.credentials.create()
+   * 3. Verifies credential with server
+   *
+   * Requires an active session. Requires `auth.experimental.passkey: true`.
+   */
+  async registerPasskey(
+    credentials?: RegisterPasskeyCredentials
+  ): Promise<AuthPasskeyRegistrationVerifyResponse> {
+    assertPasskeyExperimentalEnabled(this.experimental)
+    try {
+      if (!browserSupportsWebAuthn()) {
+        return this._returnResult({
+          data: null,
+          error: new AuthUnknownError('Browser does not support WebAuthn', null),
+        })
+      }
+
+      // 1. Get challenge options from server
+      const { data: options, error: optionsError } = await this._startPasskeyRegistration()
+      if (optionsError || !options) {
+        return this._returnResult({ data: null, error: optionsError })
+      }
+
+      // 2. Deserialize and prompt user via browser WebAuthn API
+      const publicKeyOptions = deserializeCredentialCreationOptions(options.options)
+      const signal = credentials?.options?.signal ?? webAuthnAbortService.createNewAbortSignal()
+      const { data: credential, error: credentialError } = await createCredential({
+        publicKey: publicKeyOptions,
+        signal,
+      })
+      if (credentialError || !credential) {
+        return this._returnResult({
+          data: null,
+          error: credentialError ?? new AuthUnknownError('WebAuthn ceremony failed', null),
+        })
+      }
+
+      // 3. Serialize and verify with server
+      const serialized = serializeCredentialCreationResponse(credential)
+      return this._verifyPasskeyRegistration({
+        challengeId: options.challenge_id,
+        credential: serialized,
+      })
+    } catch (error) {
+      if (isAuthError(error)) {
+        return this._returnResult({ data: null, error })
+      }
+      throw error
+    }
+  }
+
+  /**
+   * Start passkey registration for the current authenticated user.
+   * Returns WebAuthn credential creation options to pass to navigator.credentials.create().
+   */
+  private async _startPasskeyRegistration(): Promise<AuthPasskeyRegistrationOptionsResponse> {
+    assertPasskeyExperimentalEnabled(this.experimental)
+    try {
+      return await this._useSession(async (result) => {
+        const {
+          data: { session },
+          error: sessionError,
+        } = result
+        if (sessionError) {
+          return this._returnResult({ data: null, error: sessionError })
+        }
+        if (!session) {
+          return this._returnResult({ data: null, error: new AuthSessionMissingError() })
+        }
+        const { data, error } = await _request(
+          this.fetch,
+          'POST',
+          `${this.url}/passkeys/registration/options`,
+          {
+            headers: this.headers,
+            jwt: session.access_token,
+            body: {},
+          }
+        )
+        if (error) {
+          return this._returnResult({ data: null, error })
+        }
+        return this._returnResult({ data, error: null })
+      })
+    } catch (error) {
+      if (isAuthError(error)) {
+        return this._returnResult({ data: null, error })
+      }
+      throw error
+    }
+  }
+
+  /**
+   * Verify passkey registration with the credential response.
+   * The credentialResponse should be the serialized output of navigator.credentials.create().
+   */
+  private async _verifyPasskeyRegistration(
+    params: VerifyPasskeyRegistrationParams
+  ): Promise<AuthPasskeyRegistrationVerifyResponse> {
+    assertPasskeyExperimentalEnabled(this.experimental)
+    try {
+      return await this._useSession(async (result) => {
+        const {
+          data: { session },
+          error: sessionError,
+        } = result
+        if (sessionError) {
+          return this._returnResult({ data: null, error: sessionError })
+        }
+        if (!session) {
+          return this._returnResult({ data: null, error: new AuthSessionMissingError() })
+        }
+        const { data, error } = await _request(
+          this.fetch,
+          'POST',
+          `${this.url}/passkeys/registration/verify`,
+          {
+            headers: this.headers,
+            jwt: session.access_token,
+            body: {
+              challenge_id: params.challengeId,
+              credential: params.credential,
+            },
+          }
+        )
+        if (error) {
+          return this._returnResult({ data: null, error })
+        }
+        return this._returnResult({ data, error: null })
+      })
+    } catch (error) {
+      if (isAuthError(error)) {
+        return this._returnResult({ data: null, error })
+      }
+      throw error
+    }
+  }
+
+  /**
+   * Start passkey authentication.
+   * Returns WebAuthn credential request options to pass to navigator.credentials.get().
+   */
+  private async _startPasskeyAuthentication(
+    params?: StartPasskeyAuthenticationParams
+  ): Promise<AuthPasskeyAuthenticationOptionsResponse> {
+    assertPasskeyExperimentalEnabled(this.experimental)
+    try {
+      const { data, error } = await _request(
+        this.fetch,
+        'POST',
+        `${this.url}/passkeys/authentication/options`,
+        {
+          headers: this.headers,
+          body: {
+            gotrue_meta_security: { captcha_token: params?.options?.captchaToken },
+          },
+        }
+      )
+      if (error) {
+        return this._returnResult({ data: null, error })
+      }
+      return this._returnResult({ data, error: null })
+    } catch (error) {
+      if (isAuthError(error)) {
+        return this._returnResult({ data: null, error })
+      }
+      throw error
+    }
+  }
+
+  /**
+   * Verify passkey authentication and create a session.
+   * The credential should be the serialized output of navigator.credentials.get().
+   */
+  private async _verifyPasskeyAuthentication(
+    params: VerifyPasskeyAuthenticationParams
+  ): Promise<AuthPasskeyAuthenticationVerifyResponse> {
+    assertPasskeyExperimentalEnabled(this.experimental)
+    try {
+      const { data, error } = await _request(
+        this.fetch,
+        'POST',
+        `${this.url}/passkeys/authentication/verify`,
+        {
+          headers: this.headers,
+          body: {
+            challenge_id: params.challengeId,
+            credential: params.credential,
+          },
+          xform: _sessionResponse,
+        }
+      )
+      if (error) {
+        return this._returnResult({ data: null, error })
+      }
+      if (data.session) {
+        await this._saveSession(data.session)
+        await this._notifyAllSubscribers('SIGNED_IN', data.session)
+      }
+      return this._returnResult({ data, error: null })
+    } catch (error) {
+      if (isAuthError(error)) {
+        return this._returnResult({ data: null, error })
+      }
+      throw error
+    }
+  }
+
+  /**
+   * List all passkeys for the current user.
+   */
+  private async _listPasskeys(): Promise<AuthPasskeyListResponse> {
+    assertPasskeyExperimentalEnabled(this.experimental)
+    try {
+      return await this._useSession(async (result) => {
+        const {
+          data: { session },
+          error: sessionError,
+        } = result
+        if (sessionError) {
+          return this._returnResult({ data: null, error: sessionError })
+        }
+        if (!session) {
+          return this._returnResult({ data: null, error: new AuthSessionMissingError() })
+        }
+        const { data, error } = await _request(this.fetch, 'GET', `${this.url}/passkeys`, {
+          headers: this.headers,
+          jwt: session.access_token,
+          xform: (data: any) => ({ data, error: null }),
+        })
+        if (error) {
+          return this._returnResult({ data: null, error })
+        }
+        return this._returnResult({ data, error: null })
+      })
+    } catch (error) {
+      if (isAuthError(error)) {
+        return this._returnResult({ data: null, error })
+      }
+      throw error
+    }
+  }
+
+  /**
+   * Update a passkey.
+   */
+  private async _updatePasskey(params: PasskeyUpdateParams): Promise<AuthPasskeyUpdateResponse> {
+    assertPasskeyExperimentalEnabled(this.experimental)
+    try {
+      return await this._useSession(async (result) => {
+        const {
+          data: { session },
+          error: sessionError,
+        } = result
+        if (sessionError) {
+          return this._returnResult({ data: null, error: sessionError })
+        }
+        if (!session) {
+          return this._returnResult({ data: null, error: new AuthSessionMissingError() })
+        }
+        const { data, error } = await _request(
+          this.fetch,
+          'PATCH',
+          `${this.url}/passkeys/${params.passkeyId}`,
+          {
+            headers: this.headers,
+            jwt: session.access_token,
+            body: { friendly_name: params.friendlyName },
+          }
+        )
+        if (error) {
+          return this._returnResult({ data: null, error })
+        }
+        return this._returnResult({ data, error: null })
+      })
+    } catch (error) {
+      if (isAuthError(error)) {
+        return this._returnResult({ data: null, error })
+      }
+      throw error
+    }
+  }
+
+  /**
+   * Delete a passkey.
+   */
+  private async _deletePasskey(params: PasskeyDeleteParams): Promise<AuthPasskeyDeleteResponse> {
+    assertPasskeyExperimentalEnabled(this.experimental)
+    try {
+      return await this._useSession(async (result) => {
+        const {
+          data: { session },
+          error: sessionError,
+        } = result
+        if (sessionError) {
+          return this._returnResult({ data: null, error: sessionError })
+        }
+        if (!session) {
+          return this._returnResult({ data: null, error: new AuthSessionMissingError() })
+        }
+        const { error } = await _request(
+          this.fetch,
+          'DELETE',
+          `${this.url}/passkeys/${params.passkeyId}`,
+          {
+            headers: this.headers,
+            jwt: session.access_token,
+            noResolveJson: true,
+          }
+        )
+        if (error) {
+          return this._returnResult({ data: null, error })
+        }
+        return this._returnResult({ data: null, error: null })
+      })
+    } catch (error) {
+      if (isAuthError(error)) {
+        return this._returnResult({ data: null, error })
+      }
+      throw error
+    }
+  }
 }

package/src/lib/fetch.ts

@@ -30,7 +30,7 @@ export interface FetchParameters {
   signal?: AbortSignal
 }
 
-export type RequestMethodType = 'GET' | 'POST' | 'PUT' | 'DELETE'
+export type RequestMethodType = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'
 
 const _getErrorMessage = (err: any): string =>
   err.msg || err.message || err.error_description || err.error || JSON.stringify(err)

package/src/lib/helpers.ts

@@ -304,7 +304,7 @@ export async function getCodeChallengeAndMethod(
   const codeVerifier = generatePKCEVerifier()
   let storedCodeVerifier = codeVerifier
   if (isPasswordRecovery) {
-    storedCodeVerifier += '/PASSWORD_RECOVERY'
+    storedCodeVerifier += '/recovery'
   }
   await setItemAsync(storage, `${storageKey}-code-verifier`, storedCodeVerifier)
   const codeChallenge = await generatePKCEChallenge(codeVerifier)
@@ -372,6 +372,14 @@ export function validateUUID(str: string) {
   }
 }
 
+export function assertPasskeyExperimentalEnabled(experimental: { passkey?: boolean }): void {
+  if (!experimental.passkey) {
+    throw new Error(
+      '@supabase/auth-js: the passkey API is experimental and disabled by default. Enable it by passing `auth: { experimental: { passkey: true } }` to createClient (or to the GoTrueClient constructor).'
+    )
+  }
+}
+
 export function userNotAvailableProxy(): User {
   const proxyTarget = {} as User