ExSwan.Plug

Plug integration helpers for ExSwan, the Elixir WebAuthn (FIDO2) library.

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.

The package owns expiring one-time ceremony state, calls ExSwan verification, and hands persistence back to the application through explicit callbacks.

This package lives in the exswan monorepo. Related packages:

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

Installation

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

exswan_plug depends on exswan. Outside this monorepo, Hex resolves that dependency normally.

Monorepo development

When working on both packages together, set:

export EXSWAN_MONOREPO=true

With that flag set, exswan_plug uses a path dependency on ../exswan instead of the published Hex version. The root Makefile exports this for workspace commands.

Registration

{:ok, conn, options_json} =
  ExSwan.Plug.begin_registration(conn,
    user: current_user,
    user_handle: current_user.webauthn_id,
    user_name: current_user.email,
    rp_name: "Example",
    rp_id: "example.com",
    origin: "https://example.com",
    ceremony_store: {MyApp.Ceremonies, :primary},
    context: %{tenant_id: current_user.tenant_id}
  )

# Send options_json to startRegistration({optionsJSON: options_json}).
{:ok, conn, registration, persisted} =
  ExSwan.Plug.finish_registration(conn,
    response: params,
    store: MyApp.Passkeys,
    ceremony_store: {MyApp.Ceremonies, :primary}
  )

Registration requires non-nil :user and :user_handle authorization inputs.

Authentication

{:ok, conn, options_json} =
  ExSwan.Plug.begin_authentication(conn,
    rp_id: "example.com",
    origin: "https://example.com",
    allow_credentials: stored_credentials,
    ceremony_store: {MyApp.Ceremonies, :primary},
    context: %{tenant_id: tenant_id}
  )

{:ok, conn, authentication, persisted} =
  ExSwan.Plug.finish_authentication(conn,
    response: params,
    store: MyApp.Passkeys,
    ceremony_store: {MyApp.Ceremonies, :primary}
  )

The Plug session contains only a random lookup token. Challenge, RP, origin, user, and callback context remain in server-side ceremony storage. Applications must fetch the Plug session before calling these functions.

See Ceremony store adapters and Credential persistence before deploying.

Documentation

License

ExSwan.Plug is available under the MIT License.