ExSwan.Authentication (exswan v0.1.0)

View Source

Handles WebAuthn authentication ceremony operations.

This module provides functions for generating assertion request options, processing authentication responses, and verifying authentication ceremonies according to the WebAuthn specification.

Authentication Flow

  1. Generate request options with generate_request_options/2
  2. Send options to client for assertion creation
  3. Receive assertion response from client
  4. Verify the response with verify_assertion/4
  5. Update credential counter if successful

Examples

# Generate request options
rp_id = "example.com"

{:ok, options} = ExSwan.Authentication.generate_request_options(rp_id)

# After receiving assertion response from client
{:ok, result} = ExSwan.Authentication.verify_assertion(
  response, 
  options, 
  credential, 
  origin
)

Summary

Types

generate_request_options_opts()

Functions

generate_request_options(rp_id, opts \\ [])

Generates request options for authenticating with a credential.

options_to_json(options)

Converts request options to JSON-serializable format for client.

verify_assertion(response, options, credential, origins)

Verifies an authentication response and returns the verification result.

Types

generate_request_options_opts()

@type generate_request_options_opts() :: [
  challenge: binary(),
  timeout: pos_integer(),
  allow_credentials: [ExSwan.Credential.Descriptor.t() | ExSwan.Credential.t()],
  user_verification: String.t(),
  extensions: map()
]

Functions

generate_request_options(rp_id, opts \\ [])

@spec generate_request_options(String.t(), generate_request_options_opts()) ::
  {:ok, ExSwan.Assertion.RequestOptions.t()} | {:error, atom()}

Generates request options for authenticating with a credential.

Creates properly formatted options for the navigator.credentials.get() call including challenge, relying party ID, and user verification requirements.

Parameters

  • rp_id - Relying party identifier
  • opts - Optional configuration (timeout, allow_credentials, user_verification, etc.)

Options

  • :challenge - Custom challenge (defaults to secure random 32 bytes)
  • :timeout - Request timeout in milliseconds (default: 60_000)
  • :allow_credentials - List of stored credentials or credential descriptors
  • :user_verification - User verification requirement ("required", "preferred", "discouraged")
  • :extensions - WebAuthn extensions

Examples

{:ok, options} = ExSwan.Authentication.generate_request_options("example.com")

{:ok, options} = ExSwan.Authentication.generate_request_options(
  "example.com",
  allow_credentials: [credential_descriptor],
  user_verification: "required"
)

options_to_json(options)

@spec options_to_json(ExSwan.Assertion.RequestOptions.t()) :: map()

Converts request options to JSON-serializable format for client.

Encodes binary data as base64url strings and formats the options according to WebAuthn specification requirements.

verify_assertion(response, options, credential, origins)

@spec verify_assertion(
  map(),
  ExSwan.Assertion.RequestOptions.t(),
  ExSwan.Credential.t(),
  String.t() | [String.t()]
) :: {:ok, ExSwan.Assertion.Result.t()} | {:error, atom()}

Verifies an authentication response and returns the verification result.

Processes the assertion response from the client, validates the signature, verifies authenticator data, and checks security requirements.

Parameters

  • response - Raw assertion response from client
  • options - Request options used for the authentication
  • credential - Stored credential to verify against
  • origin - Expected origin for the ceremony

Returns

  • {:ok, result} - Successfully verified assertion with result data
  • {:error, reason} - Verification failure with reason

Examples

{:ok, result} = ExSwan.Authentication.verify_assertion(
  assertion_response,
  request_options,
  stored_credential,
  "https://example.com"
)