WebAuthnProvider

public protocol WebAuthnProvider : Sendable

Platform-specific WebAuthn provider interface.

Implementations trigger platform biometric / security-key prompts, handle WebAuthn credential creation and assertion, and return properly formatted byte-array results.

Sendable is required because the protocol crosses actor / task boundaries when invoked from the smart-account transaction pipeline.

Errors thrown from register or authenticate are subclasses of WebAuthnException (defined in the smart-account error module): RegistrationFailed, AuthenticationFailed, NotSupported, or Cancelled.

Example:

let provider: WebAuthnProvider = MyApplePasskeyProvider()
let registration = try await provider.register(
    challenge: challenge,
    userId: userIdBytes,
    userName: "user@example.com"
)
Show on GitHub

  • Registers a new WebAuthn credential (passkey creation).

    Triggers the platform’s credential-creation flow, prompts the user to create a new passkey using biometric authentication or a security key, generates a secp256r1 keypair and credential ID, and returns the public key plus attestation data.

    The challenge MUST be used as-is in the registration request — it is a cryptographic hash that binds the credential to the smart-account deployment.

    Throws

    WebAuthnException.RegistrationFailed, WebAuthnException.Cancelled, or WebAuthnException.NotSupported.

    Declaration

    Swift

    func register(
    challenge: Data,
    userId: Data,
    userName: String
) async throws -> WebAuthnRegistrationResult

    Parameters

    challenge

    Challenge bytes to sign (typically 32 bytes).
    userId

    User identifier bytes (typically random; used for discoverable credentials).
    userName

    User-friendly name for the credential.

    Return Value

    A WebAuthnRegistrationResult containing credential ID, public key, and attestation data.

    Show on GitHub

  • Authenticates with an existing WebAuthn credential (passkey assertion).

    Triggers the platform’s credential-assertion flow, prompts the user to authenticate, signs the challenge with the private key, and returns the signature plus authenticator data.

    The challenge MUST be used as-is in the authentication request — it is the authorization-payload hash that authorizes the transaction.

    Throws

    WebAuthnException.AuthenticationFailed, WebAuthnException.Cancelled, or WebAuthnException.NotSupported.

    Declaration

    Swift

    func authenticate(
    challenge: Data,
    allowCredentials: [WebAuthnAllowCredential]?
) async throws -> WebAuthnAuthenticationResult

    Parameters

    challenge

    Challenge bytes to sign (typically the 32-byte authorization-payload hash).
    allowCredentials

    Optional list of credential descriptors with transport hints. Constrains which passkey the authenticator uses and indicates how the client can reach the authenticator. When nil, discoverable-credential selection is used — the user picks which passkey to use. Including transport hints (e.g., hybrid) enables cross-device authentication flows such as QR-code scanning.

    Return Value

    A WebAuthnAuthenticationResult containing signature and assertion data.

    Show on GitHub