ExSwan

A security-focused WebAuthn server library for Elixir.

Alpha: The 0.x API can change, and the project has not completed its full WebAuthn conformance program. Review the validation status before production use.

ExSwan targets WebAuthn Level 2 and direct compatibility with @simplewebauthn/browser JSON. Its current compatibility evidence and intentional differences are recorded in docs/compatibility.md.

This package lives in the exswan monorepo. Related packages:

• exswan — core WebAuthn library (this package)
• exswan_plug — Plug integration helpers

Features

🔐 Covered WebAuthn Ceremonies

• Registration and authentication ceremony support
• ES256 credential support with none attestation
• Layered security validation

🛡️ Security First

• Cryptographic challenge generation
• Origin and RP ID validation
• Strict challenge, origin, RP ID, flags, and counter validation
• Secure credential storage patterns

⚡ Developer Friendly

• Clean, documented APIs
• Comprehensive error handling
• Unit, property, compatibility, and browser tests

Installation

Add exswan to your list of dependencies in mix.exs:

def deps do
  [
    {:exswan, "~> 0.1.0"}
  ]
end

Quick Start

1. Registration Flow

{:ok, %{options: options_json, ceremony: ceremony}} =
  ExSwan.generate_registration_options(
    rp_name: "Example Corp",
    rp_id: "example.com",
    user_name: "user@example.com",
    user_display_name: "John Doe",
    user_id: user_handle
  )

# Pass options_json directly to startRegistration({optionsJSON: options_json}).
{:ok, registration} =
  ExSwan.verify_registration_response(
    response: browser_response,
    expected_challenge: ceremony.challenge,
    expected_origin: "https://example.com",
    expected_rp_id: ceremony.rp_id
  )

2. Authentication Flow

{:ok, %{options: options_json, ceremony: ceremony}} =
  ExSwan.generate_authentication_options(
    rp_id: "example.com",
    allow_credentials: stored_credentials
  )

# Pass options_json directly to startAuthentication({optionsJSON: options_json}).
{:ok, authentication} =
  ExSwan.verify_authentication_response(
    response: browser_response,
    expected_challenge: ceremony.challenge,
    expected_origin: "https://example.com",
    expected_rp_id: ceremony.rp_id,
    credential: stored_credential
  )

Core Concepts

Credential Management

# Store the complete credential from registration.
credential = registration.credential

# Persist every authentication update atomically.
new_sign_count = authentication.new_sign_count
credential_backed_up = authentication.credential_backed_up

Security Considerations

• Always validate origins against your allowlist
• Use HTTPS in production environments
• Implement proper credential storage with encryption
• Regularly update dependencies for security patches
• Consider implementing rate limiting for registration/authentication endpoints
• Android SafetyNet attestation is intentionally unsupported because Google deprecated the service and its trust guarantees cannot be validated without the retired Google infrastructure. Android passkeys remain supported through none or another supported attestation format.

Documentation

• API Documentation
• Monorepo README
• Development Plan

License

ExSwan is available under the MIT License.