Init
This commit is contained in:
MarcWieland
+946
@@ -0,0 +1,946 @@
|
||||
import GoTrueClient from '../GoTrueClient'
|
||||
import { base64UrlToUint8Array, bytesToBase64URL } from './base64url'
|
||||
import { AuthError, AuthUnknownError, isAuthError } from './errors'
|
||||
import {
|
||||
AuthMFAEnrollWebauthnResponse,
|
||||
AuthMFAVerifyResponse,
|
||||
AuthMFAVerifyResponseData,
|
||||
MFAChallengeWebauthnParams,
|
||||
MFAEnrollWebauthnParams,
|
||||
MFAVerifyWebauthnParamFields,
|
||||
MFAVerifyWebauthnParams,
|
||||
RequestResult,
|
||||
StrictOmit,
|
||||
} from './types'
|
||||
import { isBrowser } from './helpers'
|
||||
import type {
|
||||
AuthenticationCredential,
|
||||
AuthenticationResponseJSON,
|
||||
AuthenticatorAttachment,
|
||||
PublicKeyCredentialCreationOptionsFuture,
|
||||
PublicKeyCredentialCreationOptionsJSON,
|
||||
PublicKeyCredentialFuture,
|
||||
PublicKeyCredentialRequestOptionsFuture,
|
||||
PublicKeyCredentialRequestOptionsJSON,
|
||||
RegistrationCredential,
|
||||
RegistrationResponseJSON,
|
||||
} from './webauthn.dom'
|
||||
|
||||
import {
|
||||
identifyAuthenticationError,
|
||||
identifyRegistrationError,
|
||||
isWebAuthnError,
|
||||
WebAuthnError,
|
||||
WebAuthnUnknownError,
|
||||
} from './webauthn.errors'
|
||||
|
||||
export { WebAuthnError, isWebAuthnError, identifyRegistrationError, identifyAuthenticationError }
|
||||
// Re-export the JSON types for use in other files
|
||||
export type { RegistrationResponseJSON, AuthenticationResponseJSON }
|
||||
|
||||
/**
|
||||
* WebAuthn abort service to manage ceremony cancellation.
|
||||
* Ensures only one WebAuthn ceremony is active at a time to prevent "operation already in progress" errors.
|
||||
*
|
||||
* @experimental This class is experimental and may change in future releases
|
||||
* @see {@link https://w3c.github.io/webauthn/#sctn-automation-webdriver-capability W3C WebAuthn Spec - Aborting Ceremonies}
|
||||
*/
|
||||
export class WebAuthnAbortService {
|
||||
private controller: AbortController | undefined
|
||||
|
||||
/**
|
||||
* Create an abort signal for a new WebAuthn operation.
|
||||
* Automatically cancels any existing operation.
|
||||
*
|
||||
* @returns {AbortSignal} Signal to pass to navigator.credentials.create() or .get()
|
||||
* @see {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal MDN - AbortSignal}
|
||||
*/
|
||||
createNewAbortSignal(): AbortSignal {
|
||||
// Abort any existing calls to navigator.credentials.create() or navigator.credentials.get()
|
||||
if (this.controller) {
|
||||
const abortError = new Error('Cancelling existing WebAuthn API call for new one')
|
||||
abortError.name = 'AbortError'
|
||||
this.controller.abort(abortError)
|
||||
}
|
||||
|
||||
const newController = new AbortController()
|
||||
this.controller = newController
|
||||
return newController.signal
|
||||
}
|
||||
|
||||
/**
|
||||
* Manually cancel the current WebAuthn operation.
|
||||
* Useful for cleaning up when user cancels or navigates away.
|
||||
*
|
||||
* @see {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortController/abort MDN - AbortController.abort}
|
||||
*/
|
||||
cancelCeremony(): void {
|
||||
if (this.controller) {
|
||||
const abortError = new Error('Manually cancelling existing WebAuthn API call')
|
||||
abortError.name = 'AbortError'
|
||||
this.controller.abort(abortError)
|
||||
this.controller = undefined
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Singleton instance to ensure only one WebAuthn ceremony is active at a time.
|
||||
* This prevents "operation already in progress" errors when retrying WebAuthn operations.
|
||||
*
|
||||
* @experimental This instance is experimental and may change in future releases
|
||||
*/
|
||||
export const webAuthnAbortService = new WebAuthnAbortService()
|
||||
|
||||
/**
|
||||
* Server response format for WebAuthn credential creation options.
|
||||
* Uses W3C standard JSON format with base64url-encoded binary fields.
|
||||
*/
|
||||
export type ServerCredentialCreationOptions = PublicKeyCredentialCreationOptionsJSON
|
||||
|
||||
/**
|
||||
* Server response format for WebAuthn credential request options.
|
||||
* Uses W3C standard JSON format with base64url-encoded binary fields.
|
||||
*/
|
||||
export type ServerCredentialRequestOptions = PublicKeyCredentialRequestOptionsJSON
|
||||
|
||||
/**
|
||||
* Convert base64url encoded strings in WebAuthn credential creation options to ArrayBuffers
|
||||
* as required by the WebAuthn browser API.
|
||||
* Supports both native WebAuthn Level 3 parseCreationOptionsFromJSON and manual fallback.
|
||||
*
|
||||
* @param {ServerCredentialCreationOptions} options - JSON options from server with base64url encoded fields
|
||||
* @returns {PublicKeyCredentialCreationOptionsFuture} Options ready for navigator.credentials.create()
|
||||
* @see {@link https://w3c.github.io/webauthn/#sctn-parseCreationOptionsFromJSON W3C WebAuthn Spec - parseCreationOptionsFromJSON}
|
||||
*/
|
||||
export function deserializeCredentialCreationOptions(
|
||||
options: ServerCredentialCreationOptions
|
||||
): PublicKeyCredentialCreationOptionsFuture {
|
||||
if (!options) {
|
||||
throw new Error('Credential creation options are required')
|
||||
}
|
||||
|
||||
// Check if the native parseCreationOptionsFromJSON method is available
|
||||
if (
|
||||
typeof PublicKeyCredential !== 'undefined' &&
|
||||
'parseCreationOptionsFromJSON' in PublicKeyCredential &&
|
||||
typeof (PublicKeyCredential as unknown as PublicKeyCredentialFuture)
|
||||
.parseCreationOptionsFromJSON === 'function'
|
||||
) {
|
||||
// Use the native WebAuthn Level 3 method
|
||||
return (
|
||||
PublicKeyCredential as unknown as PublicKeyCredentialFuture
|
||||
).parseCreationOptionsFromJSON(
|
||||
/** we assert the options here as typescript still doesn't know about future webauthn types */
|
||||
options as any
|
||||
) as PublicKeyCredentialCreationOptionsFuture
|
||||
}
|
||||
|
||||
// Fallback to manual parsing for browsers that don't support the native method
|
||||
// Destructure to separate fields that need transformation
|
||||
const { challenge: challengeStr, user: userOpts, excludeCredentials, ...restOptions } = options
|
||||
|
||||
// Convert challenge from base64url to ArrayBuffer
|
||||
const challenge = base64UrlToUint8Array(challengeStr).buffer as ArrayBuffer
|
||||
|
||||
// Convert user.id from base64url to ArrayBuffer
|
||||
const user: PublicKeyCredentialUserEntity = {
|
||||
...userOpts,
|
||||
id: base64UrlToUint8Array(userOpts.id).buffer as ArrayBuffer,
|
||||
}
|
||||
|
||||
// Build the result object
|
||||
const result: PublicKeyCredentialCreationOptionsFuture = {
|
||||
...restOptions,
|
||||
challenge,
|
||||
user,
|
||||
}
|
||||
|
||||
// Only add excludeCredentials if it exists
|
||||
if (excludeCredentials && excludeCredentials.length > 0) {
|
||||
result.excludeCredentials = new Array(excludeCredentials.length)
|
||||
|
||||
for (let i = 0; i < excludeCredentials.length; i++) {
|
||||
const cred = excludeCredentials[i]
|
||||
result.excludeCredentials[i] = {
|
||||
...cred,
|
||||
id: base64UrlToUint8Array(cred.id).buffer,
|
||||
type: cred.type || 'public-key',
|
||||
// Cast transports to handle future transport types like "cable"
|
||||
transports: cred.transports,
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return result
|
||||
}
|
||||
|
||||
/**
|
||||
* Convert base64url encoded strings in WebAuthn credential request options to ArrayBuffers
|
||||
* as required by the WebAuthn browser API.
|
||||
* Supports both native WebAuthn Level 3 parseRequestOptionsFromJSON and manual fallback.
|
||||
*
|
||||
* @param {ServerCredentialRequestOptions} options - JSON options from server with base64url encoded fields
|
||||
* @returns {PublicKeyCredentialRequestOptionsFuture} Options ready for navigator.credentials.get()
|
||||
* @see {@link https://w3c.github.io/webauthn/#sctn-parseRequestOptionsFromJSON W3C WebAuthn Spec - parseRequestOptionsFromJSON}
|
||||
*/
|
||||
export function deserializeCredentialRequestOptions(
|
||||
options: ServerCredentialRequestOptions
|
||||
): PublicKeyCredentialRequestOptionsFuture {
|
||||
if (!options) {
|
||||
throw new Error('Credential request options are required')
|
||||
}
|
||||
|
||||
// Check if the native parseRequestOptionsFromJSON method is available
|
||||
if (
|
||||
typeof PublicKeyCredential !== 'undefined' &&
|
||||
'parseRequestOptionsFromJSON' in PublicKeyCredential &&
|
||||
typeof (PublicKeyCredential as unknown as PublicKeyCredentialFuture)
|
||||
.parseRequestOptionsFromJSON === 'function'
|
||||
) {
|
||||
// Use the native WebAuthn Level 3 method
|
||||
return (
|
||||
PublicKeyCredential as unknown as PublicKeyCredentialFuture
|
||||
).parseRequestOptionsFromJSON(options) as PublicKeyCredentialRequestOptionsFuture
|
||||
}
|
||||
|
||||
// Fallback to manual parsing for browsers that don't support the native method
|
||||
// Destructure to separate fields that need transformation
|
||||
const { challenge: challengeStr, allowCredentials, ...restOptions } = options
|
||||
|
||||
// Convert challenge from base64url to ArrayBuffer
|
||||
const challenge = base64UrlToUint8Array(challengeStr).buffer as ArrayBuffer
|
||||
|
||||
// Build the result object
|
||||
const result: PublicKeyCredentialRequestOptionsFuture = {
|
||||
...restOptions,
|
||||
challenge,
|
||||
}
|
||||
|
||||
// Only add allowCredentials if it exists
|
||||
if (allowCredentials && allowCredentials.length > 0) {
|
||||
result.allowCredentials = new Array(allowCredentials.length)
|
||||
|
||||
for (let i = 0; i < allowCredentials.length; i++) {
|
||||
const cred = allowCredentials[i]
|
||||
result.allowCredentials[i] = {
|
||||
...cred,
|
||||
id: base64UrlToUint8Array(cred.id).buffer,
|
||||
type: cred.type || 'public-key',
|
||||
// Cast transports to handle future transport types like "cable"
|
||||
transports: cred.transports,
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return result
|
||||
}
|
||||
|
||||
/**
|
||||
* Server format for credential response with base64url-encoded binary fields
|
||||
* Can be either a registration or authentication response
|
||||
*/
|
||||
export type ServerCredentialResponse = RegistrationResponseJSON | AuthenticationResponseJSON
|
||||
|
||||
/**
|
||||
* Convert a registration/enrollment credential response to server format.
|
||||
* Serializes binary fields to base64url for JSON transmission.
|
||||
* Supports both native WebAuthn Level 3 toJSON and manual fallback.
|
||||
*
|
||||
* @param {RegistrationCredential} credential - Credential from navigator.credentials.create()
|
||||
* @returns {RegistrationResponseJSON} JSON-serializable credential for server
|
||||
* @see {@link https://w3c.github.io/webauthn/#dom-publickeycredential-tojson W3C WebAuthn Spec - toJSON}
|
||||
*/
|
||||
export function serializeCredentialCreationResponse(
|
||||
credential: RegistrationCredential
|
||||
): RegistrationResponseJSON {
|
||||
// Check if the credential instance has the toJSON method
|
||||
if ('toJSON' in credential && typeof credential.toJSON === 'function') {
|
||||
// Use the native WebAuthn Level 3 method
|
||||
return (credential as RegistrationCredential).toJSON()
|
||||
}
|
||||
const credentialWithAttachment = credential as PublicKeyCredential & {
|
||||
response: AuthenticatorAttestationResponse
|
||||
authenticatorAttachment?: string | null
|
||||
}
|
||||
|
||||
return {
|
||||
id: credential.id,
|
||||
rawId: credential.id,
|
||||
response: {
|
||||
attestationObject: bytesToBase64URL(new Uint8Array(credential.response.attestationObject)),
|
||||
clientDataJSON: bytesToBase64URL(new Uint8Array(credential.response.clientDataJSON)),
|
||||
},
|
||||
type: 'public-key',
|
||||
clientExtensionResults: credential.getClientExtensionResults(),
|
||||
// Convert null to undefined and cast to AuthenticatorAttachment type
|
||||
authenticatorAttachment: (credentialWithAttachment.authenticatorAttachment ?? undefined) as
|
||||
| AuthenticatorAttachment
|
||||
| undefined,
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Convert an authentication/verification credential response to server format.
|
||||
* Serializes binary fields to base64url for JSON transmission.
|
||||
* Supports both native WebAuthn Level 3 toJSON and manual fallback.
|
||||
*
|
||||
* @param {AuthenticationCredential} credential - Credential from navigator.credentials.get()
|
||||
* @returns {AuthenticationResponseJSON} JSON-serializable credential for server
|
||||
* @see {@link https://w3c.github.io/webauthn/#dom-publickeycredential-tojson W3C WebAuthn Spec - toJSON}
|
||||
*/
|
||||
export function serializeCredentialRequestResponse(
|
||||
credential: AuthenticationCredential
|
||||
): AuthenticationResponseJSON {
|
||||
// Check if the credential instance has the toJSON method
|
||||
if ('toJSON' in credential && typeof credential.toJSON === 'function') {
|
||||
// Use the native WebAuthn Level 3 method
|
||||
return (credential as AuthenticationCredential).toJSON()
|
||||
}
|
||||
|
||||
// Fallback to manual conversion for browsers that don't support toJSON
|
||||
// Access authenticatorAttachment via type assertion to handle TypeScript version differences
|
||||
// @simplewebauthn/types includes this property but base TypeScript 4.7.4 doesn't
|
||||
const credentialWithAttachment = credential as PublicKeyCredential & {
|
||||
response: AuthenticatorAssertionResponse
|
||||
authenticatorAttachment?: string | null
|
||||
}
|
||||
|
||||
const clientExtensionResults = credential.getClientExtensionResults()
|
||||
const assertionResponse = credential.response
|
||||
|
||||
return {
|
||||
id: credential.id,
|
||||
rawId: credential.id, // W3C spec expects rawId to match id for JSON format
|
||||
response: {
|
||||
authenticatorData: bytesToBase64URL(new Uint8Array(assertionResponse.authenticatorData)),
|
||||
clientDataJSON: bytesToBase64URL(new Uint8Array(assertionResponse.clientDataJSON)),
|
||||
signature: bytesToBase64URL(new Uint8Array(assertionResponse.signature)),
|
||||
userHandle: assertionResponse.userHandle
|
||||
? bytesToBase64URL(new Uint8Array(assertionResponse.userHandle))
|
||||
: undefined,
|
||||
},
|
||||
type: 'public-key',
|
||||
clientExtensionResults,
|
||||
// Convert null to undefined and cast to AuthenticatorAttachment type
|
||||
authenticatorAttachment: (credentialWithAttachment.authenticatorAttachment ?? undefined) as
|
||||
| AuthenticatorAttachment
|
||||
| undefined,
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* A simple test to determine if a hostname is a properly-formatted domain name.
|
||||
* Considers localhost valid for development environments.
|
||||
*
|
||||
* A "valid domain" is defined here: https://url.spec.whatwg.org/#valid-domain
|
||||
*
|
||||
* Regex sourced from here:
|
||||
* https://www.oreilly.com/library/view/regular-expressions-cookbook/9781449327453/ch08s15.html
|
||||
*
|
||||
* @param {string} hostname - The hostname to validate
|
||||
* @returns {boolean} True if valid domain or localhost
|
||||
* @see {@link https://url.spec.whatwg.org/#valid-domain WHATWG URL Spec - Valid Domain}
|
||||
*/
|
||||
export function isValidDomain(hostname: string): boolean {
|
||||
return (
|
||||
// Consider localhost valid as well since it's okay wrt Secure Contexts
|
||||
hostname === 'localhost' || /^([a-z0-9]+(-[a-z0-9]+)*\.)+[a-z]{2,}$/i.test(hostname)
|
||||
)
|
||||
}
|
||||
|
||||
/**
|
||||
* Determine if the browser is capable of WebAuthn.
|
||||
* Checks for necessary Web APIs: PublicKeyCredential and Credential Management.
|
||||
*
|
||||
* @returns {boolean} True if browser supports WebAuthn
|
||||
* @see {@link https://developer.mozilla.org/en-US/docs/Web/API/PublicKeyCredential#browser_compatibility MDN - PublicKeyCredential Browser Compatibility}
|
||||
*/
|
||||
export function browserSupportsWebAuthn(): boolean {
|
||||
return !!(
|
||||
isBrowser() &&
|
||||
'PublicKeyCredential' in window &&
|
||||
window.PublicKeyCredential &&
|
||||
'credentials' in navigator &&
|
||||
typeof navigator?.credentials?.create === 'function' &&
|
||||
typeof navigator?.credentials?.get === 'function'
|
||||
)
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a WebAuthn credential using the browser's credentials API.
|
||||
* Wraps navigator.credentials.create() with error handling.
|
||||
*
|
||||
* @param {CredentialCreationOptions} options - Options including publicKey parameters
|
||||
* @returns {Promise<RequestResult<RegistrationCredential, WebAuthnError>>} Created credential or error
|
||||
* @see {@link https://w3c.github.io/webauthn/#sctn-createCredential W3C WebAuthn Spec - Create Credential}
|
||||
* @see {@link https://developer.mozilla.org/en-US/docs/Web/API/CredentialsContainer/create MDN - credentials.create}
|
||||
*/
|
||||
export async function createCredential(
|
||||
options: StrictOmit<CredentialCreationOptions, 'publicKey'> & {
|
||||
publicKey: PublicKeyCredentialCreationOptionsFuture
|
||||
}
|
||||
): Promise<RequestResult<RegistrationCredential, WebAuthnError>> {
|
||||
try {
|
||||
const response = await navigator.credentials.create(
|
||||
/** we assert the type here until typescript types are updated */
|
||||
options as Parameters<typeof navigator.credentials.create>[0]
|
||||
)
|
||||
if (!response) {
|
||||
return {
|
||||
data: null,
|
||||
error: new WebAuthnUnknownError('Empty credential response', response),
|
||||
}
|
||||
}
|
||||
if (!(response instanceof PublicKeyCredential)) {
|
||||
return {
|
||||
data: null,
|
||||
error: new WebAuthnUnknownError('Browser returned unexpected credential type', response),
|
||||
}
|
||||
}
|
||||
return { data: response as RegistrationCredential, error: null }
|
||||
} catch (err) {
|
||||
return {
|
||||
data: null,
|
||||
error: identifyRegistrationError({
|
||||
error: err as Error,
|
||||
options,
|
||||
}),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Get a WebAuthn credential using the browser's credentials API.
|
||||
* Wraps navigator.credentials.get() with error handling.
|
||||
*
|
||||
* @param {CredentialRequestOptions} options - Options including publicKey parameters
|
||||
* @returns {Promise<RequestResult<AuthenticationCredential, WebAuthnError>>} Retrieved credential or error
|
||||
* @see {@link https://w3c.github.io/webauthn/#sctn-getAssertion W3C WebAuthn Spec - Get Assertion}
|
||||
* @see {@link https://developer.mozilla.org/en-US/docs/Web/API/CredentialsContainer/get MDN - credentials.get}
|
||||
*/
|
||||
export async function getCredential(
|
||||
options: StrictOmit<CredentialRequestOptions, 'publicKey'> & {
|
||||
publicKey: PublicKeyCredentialRequestOptionsFuture
|
||||
}
|
||||
): Promise<RequestResult<AuthenticationCredential, WebAuthnError>> {
|
||||
try {
|
||||
const response = await navigator.credentials.get(
|
||||
/** we assert the type here until typescript types are updated */
|
||||
options as Parameters<typeof navigator.credentials.get>[0]
|
||||
)
|
||||
if (!response) {
|
||||
return {
|
||||
data: null,
|
||||
error: new WebAuthnUnknownError('Empty credential response', response),
|
||||
}
|
||||
}
|
||||
if (!(response instanceof PublicKeyCredential)) {
|
||||
return {
|
||||
data: null,
|
||||
error: new WebAuthnUnknownError('Browser returned unexpected credential type', response),
|
||||
}
|
||||
}
|
||||
return { data: response as AuthenticationCredential, error: null }
|
||||
} catch (err) {
|
||||
return {
|
||||
data: null,
|
||||
error: identifyAuthenticationError({
|
||||
error: err as Error,
|
||||
options,
|
||||
}),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
export const DEFAULT_CREATION_OPTIONS: Partial<PublicKeyCredentialCreationOptionsFuture> = {
|
||||
hints: ['security-key'],
|
||||
authenticatorSelection: {
|
||||
authenticatorAttachment: 'cross-platform',
|
||||
requireResidentKey: false,
|
||||
/** set to preferred because older yubikeys don't have PIN/Biometric */
|
||||
userVerification: 'preferred',
|
||||
residentKey: 'discouraged',
|
||||
},
|
||||
attestation: 'direct',
|
||||
}
|
||||
|
||||
export const DEFAULT_REQUEST_OPTIONS: Partial<PublicKeyCredentialRequestOptionsFuture> = {
|
||||
/** set to preferred because older yubikeys don't have PIN/Biometric */
|
||||
userVerification: 'preferred',
|
||||
hints: ['security-key'],
|
||||
attestation: 'direct',
|
||||
}
|
||||
|
||||
function deepMerge<T>(...sources: Partial<T>[]): T {
|
||||
const isObject = (val: unknown): val is Record<string, unknown> =>
|
||||
val !== null && typeof val === 'object' && !Array.isArray(val)
|
||||
|
||||
const isArrayBufferLike = (val: unknown): val is ArrayBuffer | ArrayBufferView =>
|
||||
val instanceof ArrayBuffer || ArrayBuffer.isView(val)
|
||||
|
||||
const result: Partial<T> = {}
|
||||
|
||||
for (const source of sources) {
|
||||
if (!source) continue
|
||||
|
||||
for (const key in source) {
|
||||
const value = source[key]
|
||||
if (value === undefined) continue
|
||||
|
||||
if (Array.isArray(value)) {
|
||||
// preserve array reference, including unions like AuthenticatorTransport[]
|
||||
result[key] = value as T[typeof key]
|
||||
} else if (isArrayBufferLike(value)) {
|
||||
result[key] = value as T[typeof key]
|
||||
} else if (isObject(value)) {
|
||||
const existing = result[key]
|
||||
if (isObject(existing)) {
|
||||
result[key] = deepMerge(existing, value) as unknown as T[typeof key]
|
||||
} else {
|
||||
result[key] = deepMerge(value) as unknown as T[typeof key]
|
||||
}
|
||||
} else {
|
||||
result[key] = value as T[typeof key]
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return result as T
|
||||
}
|
||||
|
||||
/**
|
||||
* Merges WebAuthn credential creation options with overrides.
|
||||
* Sets sensible defaults for authenticator selection and extensions.
|
||||
*
|
||||
* @param {PublicKeyCredentialCreationOptionsFuture} baseOptions - The base options from the server
|
||||
* @param {PublicKeyCredentialCreationOptionsFuture} overrides - Optional overrides to apply
|
||||
* @param {string} friendlyName - Optional friendly name for the credential
|
||||
* @returns {PublicKeyCredentialCreationOptionsFuture} Merged credential creation options
|
||||
* @see {@link https://w3c.github.io/webauthn/#dictdef-authenticatorselectioncriteria W3C WebAuthn Spec - AuthenticatorSelectionCriteria}
|
||||
*/
|
||||
export function mergeCredentialCreationOptions(
|
||||
baseOptions: PublicKeyCredentialCreationOptionsFuture,
|
||||
overrides?: Partial<PublicKeyCredentialCreationOptionsFuture>
|
||||
): PublicKeyCredentialCreationOptionsFuture {
|
||||
return deepMerge(DEFAULT_CREATION_OPTIONS, baseOptions, overrides || {})
|
||||
}
|
||||
|
||||
/**
|
||||
* Merges WebAuthn credential request options with overrides.
|
||||
* Sets sensible defaults for user verification and hints.
|
||||
*
|
||||
* @param {PublicKeyCredentialRequestOptionsFuture} baseOptions - The base options from the server
|
||||
* @param {PublicKeyCredentialRequestOptionsFuture} overrides - Optional overrides to apply
|
||||
* @returns {PublicKeyCredentialRequestOptionsFuture} Merged credential request options
|
||||
* @see {@link https://w3c.github.io/webauthn/#dictdef-publickeycredentialrequestoptions W3C WebAuthn Spec - PublicKeyCredentialRequestOptions}
|
||||
*/
|
||||
export function mergeCredentialRequestOptions(
|
||||
baseOptions: PublicKeyCredentialRequestOptionsFuture,
|
||||
overrides?: Partial<PublicKeyCredentialRequestOptionsFuture>
|
||||
): PublicKeyCredentialRequestOptionsFuture {
|
||||
return deepMerge(DEFAULT_REQUEST_OPTIONS, baseOptions, overrides || {})
|
||||
}
|
||||
|
||||
/**
|
||||
* WebAuthn API wrapper for Supabase Auth.
|
||||
* Provides methods for enrolling, challenging, verifying, authenticating, and registering WebAuthn credentials.
|
||||
*
|
||||
* @experimental This API is experimental and may change in future releases
|
||||
* @see {@link https://w3c.github.io/webauthn/ W3C WebAuthn Specification}
|
||||
* @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Web_Authentication_API MDN - Web Authentication API}
|
||||
*/
|
||||
export class WebAuthnApi {
|
||||
public enroll: typeof WebAuthnApi.prototype._enroll
|
||||
public challenge: typeof WebAuthnApi.prototype._challenge
|
||||
public verify: typeof WebAuthnApi.prototype._verify
|
||||
public authenticate: typeof WebAuthnApi.prototype._authenticate
|
||||
public register: typeof WebAuthnApi.prototype._register
|
||||
|
||||
constructor(private client: GoTrueClient) {
|
||||
// Bind all methods so they can be destructured
|
||||
this.enroll = this._enroll.bind(this)
|
||||
this.challenge = this._challenge.bind(this)
|
||||
this.verify = this._verify.bind(this)
|
||||
this.authenticate = this._authenticate.bind(this)
|
||||
this.register = this._register.bind(this)
|
||||
}
|
||||
|
||||
/**
|
||||
* Enroll a new WebAuthn factor.
|
||||
* Creates an unverified WebAuthn factor that must be verified with a credential.
|
||||
*
|
||||
* @experimental This method is experimental and may change in future releases
|
||||
* @param {Omit<MFAEnrollWebauthnParams, 'factorType'>} params - Enrollment parameters (friendlyName required)
|
||||
* @returns {Promise<AuthMFAEnrollWebauthnResponse>} Enrolled factor details or error
|
||||
* @see {@link https://w3c.github.io/webauthn/#sctn-registering-a-new-credential W3C WebAuthn Spec - Registering a New Credential}
|
||||
*/
|
||||
public async _enroll(
|
||||
params: Omit<MFAEnrollWebauthnParams, 'factorType'>
|
||||
): Promise<AuthMFAEnrollWebauthnResponse> {
|
||||
return this.client.mfa.enroll({ ...params, factorType: 'webauthn' })
|
||||
}
|
||||
|
||||
/**
|
||||
* Challenge for WebAuthn credential creation or authentication.
|
||||
* Combines server challenge with browser credential operations.
|
||||
* Handles both registration (create) and authentication (request) flows.
|
||||
*
|
||||
* @experimental This method is experimental and may change in future releases
|
||||
* @param {MFAChallengeWebauthnParams & { friendlyName?: string; signal?: AbortSignal }} params - Challenge parameters including factorId
|
||||
* @param {Object} overrides - Allows you to override the parameters passed to navigator.credentials
|
||||
* @param {PublicKeyCredentialCreationOptionsFuture} overrides.create - Override options for credential creation
|
||||
* @param {PublicKeyCredentialRequestOptionsFuture} overrides.request - Override options for credential request
|
||||
* @returns {Promise<RequestResult>} Challenge response with credential or error
|
||||
* @see {@link https://w3c.github.io/webauthn/#sctn-credential-creation W3C WebAuthn Spec - Credential Creation}
|
||||
* @see {@link https://w3c.github.io/webauthn/#sctn-verifying-assertion W3C WebAuthn Spec - Verifying Assertion}
|
||||
*/
|
||||
public async _challenge(
|
||||
{
|
||||
factorId,
|
||||
webauthn,
|
||||
friendlyName,
|
||||
signal,
|
||||
}: MFAChallengeWebauthnParams & { friendlyName?: string; signal?: AbortSignal },
|
||||
overrides?:
|
||||
| {
|
||||
create?: Partial<PublicKeyCredentialCreationOptionsFuture>
|
||||
request?: never
|
||||
}
|
||||
| {
|
||||
create?: never
|
||||
request?: Partial<PublicKeyCredentialRequestOptionsFuture>
|
||||
}
|
||||
): Promise<
|
||||
RequestResult<
|
||||
{ factorId: string; challengeId: string } & {
|
||||
webauthn: StrictOmit<
|
||||
MFAVerifyWebauthnParamFields<'create' | 'request'>['webauthn'],
|
||||
'rpId' | 'rpOrigins'
|
||||
>
|
||||
},
|
||||
WebAuthnError | AuthError
|
||||
>
|
||||
> {
|
||||
try {
|
||||
// Get challenge from server using the client's MFA methods
|
||||
const { data: challengeResponse, error: challengeError } = await this.client.mfa.challenge({
|
||||
factorId,
|
||||
webauthn,
|
||||
})
|
||||
|
||||
if (!challengeResponse) {
|
||||
return { data: null, error: challengeError }
|
||||
}
|
||||
|
||||
const abortSignal = signal ?? webAuthnAbortService.createNewAbortSignal()
|
||||
|
||||
/** webauthn will fail if either of the name/displayname are blank */
|
||||
if (challengeResponse.webauthn.type === 'create') {
|
||||
const { user } = challengeResponse.webauthn.credential_options.publicKey
|
||||
if (!user.name) {
|
||||
// Preserve original format: use friendlyName if provided, otherwise fetch fallback
|
||||
// This maintains backward compatibility with the ${user.id}:${name} format
|
||||
const nameToUse = friendlyName
|
||||
if (!nameToUse) {
|
||||
// Only fetch user data if friendlyName is not provided (bug fix for null friendlyName)
|
||||
const currentUser = await this.client.getUser()
|
||||
const userData = currentUser.data.user
|
||||
const fallbackName =
|
||||
userData?.user_metadata?.name || userData?.email || userData?.id || 'User'
|
||||
user.name = `${user.id}:${fallbackName}`
|
||||
} else {
|
||||
user.name = `${user.id}:${nameToUse}`
|
||||
}
|
||||
}
|
||||
if (!user.displayName) {
|
||||
user.displayName = user.name
|
||||
}
|
||||
}
|
||||
|
||||
switch (challengeResponse.webauthn.type) {
|
||||
case 'create': {
|
||||
const options = mergeCredentialCreationOptions(
|
||||
challengeResponse.webauthn.credential_options.publicKey,
|
||||
overrides?.create
|
||||
)
|
||||
|
||||
const { data, error } = await createCredential({
|
||||
publicKey: options,
|
||||
signal: abortSignal,
|
||||
})
|
||||
|
||||
if (data) {
|
||||
return {
|
||||
data: {
|
||||
factorId,
|
||||
challengeId: challengeResponse.id,
|
||||
webauthn: {
|
||||
type: challengeResponse.webauthn.type,
|
||||
credential_response: data,
|
||||
},
|
||||
},
|
||||
error: null,
|
||||
}
|
||||
}
|
||||
return { data: null, error }
|
||||
}
|
||||
|
||||
case 'request': {
|
||||
const options = mergeCredentialRequestOptions(
|
||||
challengeResponse.webauthn.credential_options.publicKey,
|
||||
overrides?.request
|
||||
)
|
||||
|
||||
const { data, error } = await getCredential({
|
||||
...challengeResponse.webauthn.credential_options,
|
||||
publicKey: options,
|
||||
signal: abortSignal,
|
||||
})
|
||||
|
||||
if (data) {
|
||||
return {
|
||||
data: {
|
||||
factorId,
|
||||
challengeId: challengeResponse.id,
|
||||
webauthn: {
|
||||
type: challengeResponse.webauthn.type,
|
||||
credential_response: data,
|
||||
},
|
||||
},
|
||||
error: null,
|
||||
}
|
||||
}
|
||||
return { data: null, error }
|
||||
}
|
||||
}
|
||||
} catch (error) {
|
||||
if (isAuthError(error)) {
|
||||
return { data: null, error }
|
||||
}
|
||||
return {
|
||||
data: null,
|
||||
error: new AuthUnknownError('Unexpected error in challenge', error),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Verify a WebAuthn credential with the server.
|
||||
* Completes the WebAuthn ceremony by sending the credential to the server for verification.
|
||||
*
|
||||
* @experimental This method is experimental and may change in future releases
|
||||
* @param {Object} params - Verification parameters
|
||||
* @param {string} params.challengeId - ID of the challenge being verified
|
||||
* @param {string} params.factorId - ID of the WebAuthn factor
|
||||
* @param {MFAVerifyWebauthnParams<T>['webauthn']} params.webauthn - WebAuthn credential response
|
||||
* @returns {Promise<AuthMFAVerifyResponse>} Verification result with session or error
|
||||
* @see {@link https://w3c.github.io/webauthn/#sctn-verifying-assertion W3C WebAuthn Spec - Verifying an Authentication Assertion}
|
||||
* */
|
||||
public async _verify<T extends 'create' | 'request'>({
|
||||
challengeId,
|
||||
factorId,
|
||||
webauthn,
|
||||
}: {
|
||||
challengeId: string
|
||||
factorId: string
|
||||
webauthn: MFAVerifyWebauthnParams<T>['webauthn']
|
||||
}): Promise<AuthMFAVerifyResponse> {
|
||||
return this.client.mfa.verify({
|
||||
factorId,
|
||||
challengeId,
|
||||
webauthn: webauthn,
|
||||
})
|
||||
}
|
||||
|
||||
/**
|
||||
* Complete WebAuthn authentication flow.
|
||||
* Performs challenge and verification in a single operation for existing credentials.
|
||||
*
|
||||
* @experimental This method is experimental and may change in future releases
|
||||
* @param {Object} params - Authentication parameters
|
||||
* @param {string} params.factorId - ID of the WebAuthn factor to authenticate with
|
||||
* @param {Object} params.webauthn - WebAuthn configuration
|
||||
* @param {string} params.webauthn.rpId - Relying Party ID (defaults to current hostname)
|
||||
* @param {string[]} params.webauthn.rpOrigins - Allowed origins (defaults to current origin)
|
||||
* @param {AbortSignal} params.webauthn.signal - Optional abort signal
|
||||
* @param {PublicKeyCredentialRequestOptionsFuture} overrides - Override options for navigator.credentials.get
|
||||
* @returns {Promise<RequestResult<AuthMFAVerifyResponseData, WebAuthnError | AuthError>>} Authentication result
|
||||
* @see {@link https://w3c.github.io/webauthn/#sctn-authentication W3C WebAuthn Spec - Authentication Ceremony}
|
||||
* @see {@link https://developer.mozilla.org/en-US/docs/Web/API/PublicKeyCredentialRequestOptions MDN - PublicKeyCredentialRequestOptions}
|
||||
*/
|
||||
public async _authenticate(
|
||||
{
|
||||
factorId,
|
||||
webauthn: {
|
||||
rpId = typeof window !== 'undefined' ? window.location.hostname : undefined,
|
||||
rpOrigins = typeof window !== 'undefined' ? [window.location.origin] : undefined,
|
||||
signal,
|
||||
} = {},
|
||||
}: {
|
||||
factorId: string
|
||||
webauthn?: {
|
||||
rpId?: string
|
||||
rpOrigins?: string[]
|
||||
signal?: AbortSignal
|
||||
}
|
||||
},
|
||||
overrides?: PublicKeyCredentialRequestOptionsFuture
|
||||
): Promise<RequestResult<AuthMFAVerifyResponseData, WebAuthnError | AuthError>> {
|
||||
if (!rpId) {
|
||||
return {
|
||||
data: null,
|
||||
error: new AuthError('rpId is required for WebAuthn authentication'),
|
||||
}
|
||||
}
|
||||
try {
|
||||
if (!browserSupportsWebAuthn()) {
|
||||
return {
|
||||
data: null,
|
||||
error: new AuthUnknownError('Browser does not support WebAuthn', null),
|
||||
}
|
||||
}
|
||||
|
||||
// Get challenge and credential
|
||||
const { data: challengeResponse, error: challengeError } = await this.challenge(
|
||||
{
|
||||
factorId,
|
||||
webauthn: { rpId, rpOrigins },
|
||||
signal,
|
||||
},
|
||||
{ request: overrides }
|
||||
)
|
||||
|
||||
if (!challengeResponse) {
|
||||
return { data: null, error: challengeError }
|
||||
}
|
||||
|
||||
const { webauthn } = challengeResponse
|
||||
|
||||
// Verify credential
|
||||
return this._verify({
|
||||
factorId,
|
||||
challengeId: challengeResponse.challengeId,
|
||||
webauthn: {
|
||||
type: webauthn.type,
|
||||
rpId,
|
||||
rpOrigins,
|
||||
credential_response: webauthn.credential_response,
|
||||
},
|
||||
})
|
||||
} catch (error) {
|
||||
if (isAuthError(error)) {
|
||||
return { data: null, error }
|
||||
}
|
||||
return {
|
||||
data: null,
|
||||
error: new AuthUnknownError('Unexpected error in authenticate', error),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Complete WebAuthn registration flow.
|
||||
* Performs enrollment, challenge, and verification in a single operation for new credentials.
|
||||
*
|
||||
* @experimental This method is experimental and may change in future releases
|
||||
* @param {Object} params - Registration parameters
|
||||
* @param {string} params.friendlyName - User-friendly name for the credential
|
||||
* @param {string} params.rpId - Relying Party ID (defaults to current hostname)
|
||||
* @param {string[]} params.rpOrigins - Allowed origins (defaults to current origin)
|
||||
* @param {AbortSignal} params.signal - Optional abort signal
|
||||
* @param {PublicKeyCredentialCreationOptionsFuture} overrides - Override options for navigator.credentials.create
|
||||
* @returns {Promise<RequestResult<AuthMFAVerifyResponseData, WebAuthnError | AuthError>>} Registration result
|
||||
* @see {@link https://w3c.github.io/webauthn/#sctn-registering-a-new-credential W3C WebAuthn Spec - Registration Ceremony}
|
||||
* @see {@link https://developer.mozilla.org/en-US/docs/Web/API/PublicKeyCredentialCreationOptions MDN - PublicKeyCredentialCreationOptions}
|
||||
*/
|
||||
public async _register(
|
||||
{
|
||||
friendlyName,
|
||||
webauthn: {
|
||||
rpId = typeof window !== 'undefined' ? window.location.hostname : undefined,
|
||||
rpOrigins = typeof window !== 'undefined' ? [window.location.origin] : undefined,
|
||||
signal,
|
||||
} = {},
|
||||
}: {
|
||||
friendlyName: string
|
||||
webauthn?: {
|
||||
rpId?: string
|
||||
rpOrigins?: string[]
|
||||
signal?: AbortSignal
|
||||
}
|
||||
},
|
||||
overrides?: Partial<PublicKeyCredentialCreationOptionsFuture>
|
||||
): Promise<RequestResult<AuthMFAVerifyResponseData, WebAuthnError | AuthError>> {
|
||||
if (!rpId) {
|
||||
return {
|
||||
data: null,
|
||||
error: new AuthError('rpId is required for WebAuthn registration'),
|
||||
}
|
||||
}
|
||||
try {
|
||||
if (!browserSupportsWebAuthn()) {
|
||||
return {
|
||||
data: null,
|
||||
error: new AuthUnknownError('Browser does not support WebAuthn', null),
|
||||
}
|
||||
}
|
||||
|
||||
// Enroll factor
|
||||
const { data: factor, error: enrollError } = await this._enroll({
|
||||
friendlyName,
|
||||
})
|
||||
|
||||
if (!factor) {
|
||||
await this.client.mfa
|
||||
.listFactors()
|
||||
.then((factors) =>
|
||||
factors.data?.all.find(
|
||||
(v) =>
|
||||
v.factor_type === 'webauthn' &&
|
||||
v.friendly_name === friendlyName &&
|
||||
v.status !== 'unverified'
|
||||
)
|
||||
)
|
||||
.then((factor) => (factor ? this.client.mfa.unenroll({ factorId: factor?.id }) : void 0))
|
||||
return { data: null, error: enrollError }
|
||||
}
|
||||
|
||||
// Get challenge and create credential
|
||||
const { data: challengeResponse, error: challengeError } = await this._challenge(
|
||||
{
|
||||
factorId: factor.id,
|
||||
friendlyName: factor.friendly_name,
|
||||
webauthn: { rpId, rpOrigins },
|
||||
signal,
|
||||
},
|
||||
{
|
||||
create: overrides,
|
||||
}
|
||||
)
|
||||
|
||||
if (!challengeResponse) {
|
||||
return { data: null, error: challengeError }
|
||||
}
|
||||
|
||||
return this._verify({
|
||||
factorId: factor.id,
|
||||
challengeId: challengeResponse.challengeId,
|
||||
webauthn: {
|
||||
rpId,
|
||||
rpOrigins,
|
||||
type: challengeResponse.webauthn.type,
|
||||
credential_response: challengeResponse.webauthn.credential_response,
|
||||
},
|
||||
})
|
||||
} catch (error) {
|
||||
if (isAuthError(error)) {
|
||||
return { data: null, error }
|
||||
}
|
||||
return {
|
||||
data: null,
|
||||
error: new AuthUnknownError('Unexpected error in register', error),
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user