ExSwan.Plug (exswan_plug v0.1.0)

Plug integration helpers for ExSwan.

Ceremony helpers keep challenges in server-side storage and put only opaque lookup tokens in the Plug session. Applications retain identity and persistence policy through the ExSwan.Plug.Store callbacks.

Installation

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

When developing inside the exswan monorepo, depend on the path package and set EXSWAN_MONOREPO=true so :exswan resolves from packages/exswan.

Summary

Types

ceremony_store()

A ceremony-store module and its adapter-specific context.

Functions

begin_authentication(conn, opts)

Begins an authentication ceremony.

begin_registration(conn, opts)

Begins an authorized registration ceremony.

finish_authentication(conn, opts)

Consumes and verifies an authentication ceremony, then atomically persists its counter and backup-state result through update_credential/3.

finish_registration(conn, opts)

Consumes and verifies a registration ceremony, then invokes create_credential/3.

validate_config(opts)

Validates relying-party configuration.

version()

Returns the library version.

Types

ceremony_store()

@type ceremony_store() :: {module(), term()}

A ceremony-store module and its adapter-specific context.

Functions

begin_authentication(conn, opts)

@spec begin_authentication(
  Plug.Conn.t(),
  keyword()
) :: {:ok, Plug.Conn.t(), map()} | {:error, term()}

Begins an authentication ceremony.

Required options are :rp_id, :origin, and :ceremony_store. Pass stored credentials with :allow_credentials when the account is known in advance.

begin_registration(conn, opts)

@spec begin_registration(
  Plug.Conn.t(),
  keyword()
) :: {:ok, Plug.Conn.t(), map()} | {:error, term()}

Begins an authorized registration ceremony.

Required options are :user, :user_handle, :user_name, :rp_name, :rp_id, :origin, and :ceremony_store. The returned options are browser-ready.

finish_authentication(conn, opts)

@spec finish_authentication(
  Plug.Conn.t(),
  keyword()
) ::
  {:ok, Plug.Conn.t(), ExSwan.AuthenticationResult.t(), term()}
  | {:error, term()}

Consumes and verifies an authentication ceremony, then atomically persists its counter and backup-state result through update_credential/3.

finish_registration(conn, opts)

@spec finish_registration(
  Plug.Conn.t(),
  keyword()
) ::
  {:ok, Plug.Conn.t(), ExSwan.RegistrationResult.t(), term()} | {:error, term()}

Consumes and verifies a registration ceremony, then invokes create_credential/3.

Ceremony state is consumed before verification, so failed and concurrent retries cannot reuse an attacker-controlled response.

validate_config(opts)

@spec validate_config(keyword()) :: :ok | {:error, term()}

Validates relying-party configuration.

Origins must be absolute HTTPS URLs without userinfo, query, or fragment. HTTP is accepted only for localhost development.

version()

@spec version() :: String.t()

Returns the library version.