SigilGuard.Identity behaviour (SigilGuard v0.2.0)

Identity provider behaviour and trust levels for the SIGIL protocol.

Trust levels form a monotonic hierarchy — higher levels subsume lower ones. Matches the sigil-protocol Rust crate's TrustLevel enum (v0.1.5).

Trust Level Hierarchy

:low < :medium < :high

low — Anonymous or unverified user. Rate-limited, scan-only access.
medium — Verified identity (email, OIDC, social login). Standard access.
high — Strong verification (eIDAS, government ID, hardware key). Full access.

Implementing an Identity Provider

defmodule MyApp.SessionIdentity do
  @behaviour SigilGuard.Identity

  @impl true
  def identity(context) do
    "did:web:" <> context.user_id
  end

  @impl true
  def trust_level(context) do
    if context.verified?, do: :high, else: :medium
  end

  @impl true
  def bindings(context) do
    ["session:" <> context.session_id]
  end
end

Summary

Types

trust_level()

Callbacks

bindings(context)

Return a list of binding identifiers (session, device, etc.) for the given context.

identity(context)

Return the identity string (e.g., DID, principal ID) for the given context.

trust_level(context)

Return the trust level for the given context.

Functions

compare_trust(a, b)

Compare two trust levels.

sufficient_trust?(actual, required)

Check if actual trust level meets or exceeds the required trust level.

trust_levels()

Return all trust levels in ascending order.

Types

trust_level()

@type trust_level() :: :low | :medium | :high

Callbacks

bindings(context)

@callback bindings(context :: term()) :: [String.t()]

Return a list of binding identifiers (session, device, etc.) for the given context.

identity(context)

@callback identity(context :: term()) :: String.t()

Return the identity string (e.g., DID, principal ID) for the given context.

trust_level(context)

@callback trust_level(context :: term()) :: trust_level()

Return the trust level for the given context.

Functions

compare_trust(a, b)

@spec compare_trust(trust_level(), trust_level()) :: :lt | :eq | :gt

Compare two trust levels.

Returns :lt, :eq, or :gt following the trust hierarchy.

Examples

iex> SigilGuard.Identity.compare_trust(:low, :high)
:lt

iex> SigilGuard.Identity.compare_trust(:high, :medium)
:gt

iex> SigilGuard.Identity.compare_trust(:medium, :medium)
:eq

sufficient_trust?(actual, required)

@spec sufficient_trust?(trust_level(), trust_level()) :: boolean()

Check if actual trust level meets or exceeds the required trust level.

Examples

iex> SigilGuard.Identity.sufficient_trust?(:high, :medium)
true

iex> SigilGuard.Identity.sufficient_trust?(:low, :high)
false

trust_levels()

@spec trust_levels() :: [trust_level(), ...]

Return all trust levels in ascending order.

Examples

iex> SigilGuard.Identity.trust_levels()
[:low, :medium, :high]