Exosphere.ATProto.Identity.Handle (Exosphere v0.4.0)

Handle resolution for Exosphere.ATProto.

Handles are DNS domain names that resolve to DIDs. Resolution can occur via:

DNS TXT record at _atproto.<handle>
HTTPS well-known endpoint at https://<handle>/.well-known/atproto-did

Examples

# Resolve a handle to its DID
{:ok, did} = Exosphere.ATProto.Identity.Handle.resolve("alice.bsky.social")
# => {:ok, "did:plc:z72i7hdynmk6r22z27h6tvur"}

# Validate handle syntax
Exosphere.ATProto.Identity.Handle.valid?("alice.example.com")
# => true

Summary

Types

resolve_opts()

Functions

normalize(handle)

Normalize a handle to lowercase.

resolve(handle, opts \\ [])

Resolve a handle to its DID.

resolve_dns(handle)

Resolve a handle via DNS TXT record.

resolve_https(handle, opts \\ [])

Resolve a handle via HTTPS well-known endpoint.

valid?(handle)

Validate handle syntax.

Types

resolve_opts()

@type resolve_opts() :: [
  timeout: pos_integer(),
  methods: [:dns | :https],
  http_client: module()
]

Functions

normalize(handle)

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

Normalize a handle to lowercase.

resolve(handle, opts \\ [])

@spec resolve(String.t(), resolve_opts()) :: {:ok, String.t()} | {:error, term()}

Resolve a handle to its DID.

Tries DNS TXT record first, then falls back to HTTPS well-known endpoint.

Options

:timeout - Request timeout in milliseconds (default: 10_000)
:methods - Resolution methods to try (default: [:dns, :https])
:http_client - HTTP client module implementing HTTP.Behaviour (default: Exosphere.ATProto.HTTP; useful for testing)

resolve_dns(handle)

@spec resolve_dns(String.t()) :: {:ok, String.t()} | {:error, term()}

Resolve a handle via DNS TXT record.

Queries _atproto.<handle> for a TXT record containing the DID.

resolve_https(handle, opts \\ [])

@spec resolve_https(String.t(), resolve_opts()) ::
  {:ok, String.t()} | {:error, term()}

Resolve a handle via HTTPS well-known endpoint.

Fetches https://<handle>/.well-known/atproto-did.

valid?(handle)

@spec valid?(String.t()) :: boolean()

Validate handle syntax.

Handles must be valid domain names with:

At least one dot
Only allowed characters (letters, digits, hyphens, dots)
No consecutive dots or leading/trailing dots
Labels between 1-63 characters
Total length under 253 characters
A final segment (the TLD) that does not start with a digit