@supabase/auth-js 3.0.0-next.5 → 3.0.0-next.6

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.
@@ -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
@@ -5912,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

@@ -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
 

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,
@@ -174,6 +180,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
@@ -2624,3 +2651,154 @@ export interface AuthOAuthServerApi {
    */
   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
+  startRegistration(): Promise<AuthPasskeyRegistrationOptionsResponse>
+  verifyRegistration(
+    params: VerifyPasskeyRegistrationParams
+  ): Promise<AuthPasskeyRegistrationVerifyResponse>
+
+  // Two-step authentication
+  startAuthentication(
+    params?: StartPasskeyAuthenticationParams
+  ): Promise<AuthPasskeyAuthenticationOptionsResponse>
+  verifyAuthentication(
+    params: VerifyPasskeyAuthenticationParams
+  ): Promise<AuthPasskeyAuthenticationVerifyResponse>
+
+  // Management
+  list(): Promise<AuthPasskeyListResponse>
+  update(params: PasskeyUpdateParams): Promise<AuthPasskeyUpdateResponse>
+  delete(params: PasskeyDeleteParams): Promise<AuthPasskeyDeleteResponse>
+}
+
+export interface GoTrueAdminPasskeyApi {
+  listPasskeys(params: AuthPasskeyAdminListParams): Promise<AuthPasskeyListResponse>
+  deletePasskey(params: AuthPasskeyAdminDeleteParams): Promise<AuthPasskeyDeleteResponse>
+}