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

Extracts the advertisement secret key from a QR code string.

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

Extracts the identity key from a QR code string.

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

Extracts the noise key from a QR code string.

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

Extracts the reference from a QR code string.

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

Formats a QR code for display (e.g., in terminal or UI).

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

Convenience function that generates a QR string and renders it as terminal output.

Takes authentication components and returns a formatted ASCII QR code.

@spec generate_qr_string(String.t(), String.t(), String.t(), String.t()) :: String.t()

Generates a QR code string from authentication components.

The QR code format is: "ref,noiseKeyB64,identityKeyB64,advSecretKeyB64"

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

Generates a QR code reference string.

This creates a unique reference string for QR code generation.

@spec generate_refs(integer()) :: [String.t()]

Generates multiple QR code references.

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

Parses a QR code string into its components.

Returns {:ok, {ref, noise_key_b64, identity_key_b64, adv_secret_key_b64}} on success, or {:error, reason} on failure.

@spec qr_expired?(integer(), integer()) :: boolean()

Checks if a QR code has expired based on its generation time.

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

Renders a QR string as ASCII art using the qr_code library.

Takes a QR string and returns an ASCII representation of the QR code matrix. Uses half-height blocks to correct for terminal character aspect ratio.

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

Renders a QR string with pretty terminal formatting including borders and branding.

Takes a QR string and returns a formatted ASCII QR code suitable for terminal display.

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

Validates a QR code string format.