Vaultx.Secrets.TOTP.Behaviour behaviour (Vaultx v0.7.0)
View SourceBehaviour definition for HashiCorp Vault TOTP secrets engine operations.
This behaviour defines the interface that TOTP secrets engine implementations must provide, ensuring consistency and type safety across different implementations.
Core Operations
The TOTP secrets engine supports the following operations:
Key Management Operations
create_key/3- Create or update a TOTP keyread_key/2- Read a TOTP key configurationlist_keys/1- List all configured keysdelete_key/2- Delete a TOTP key
Code Operations
generate_code/2- Generate a TOTP code for a keyvalidate_code/3- Validate a TOTP code against a key
API Compliance
This behaviour ensures compliance with:
Summary
Types
Result of a key creation operation.
Result of a key delete operation.
Result of a code generation operation.
TOTP key configuration parameters.
TOTP key creation response with optional QR code and URL.
TOTP key information returned from read operations.
TOTP key name. Must be a non-empty string with valid characters.
Result of a key list operation.
Options for TOTP secrets engine operations.
Result of a key read operation.
Generated TOTP code.
Result of a code validation operation.
TOTP code validation result.
Callbacks
Create or update a TOTP key.
Delete a TOTP key.
Generate a TOTP code for a key.
List all configured TOTP keys.
Read a TOTP key configuration.
Validate a TOTP code against a key.
Types
@type create_key_result() :: {:ok, key_creation_response()} | {:error, Vaultx.Base.Error.t()}
Result of a key creation operation.
@type delete_key_result() :: :ok | {:error, Vaultx.Base.Error.t()}
Result of a key delete operation.
@type generate_code_result() :: {:ok, totp_code()} | {:error, Vaultx.Base.Error.t()}
Result of a code generation operation.
@type key_config() :: %{ optional(:generate) => boolean(), optional(:exported) => boolean(), optional(:key_size) => pos_integer(), optional(:url) => String.t(), optional(:key) => String.t(), optional(:issuer) => String.t(), optional(:account_name) => String.t(), optional(:period) => pos_integer(), optional(:algorithm) => String.t(), optional(:digits) => pos_integer(), optional(:skew) => non_neg_integer(), optional(:qr_size) => non_neg_integer() }
TOTP key configuration parameters.
@type key_creation_response() :: %{ optional(:barcode) => String.t(), optional(:url) => String.t() }
TOTP key creation response with optional QR code and URL.
@type key_info() :: %{ account_name: String.t(), algorithm: String.t(), digits: pos_integer(), issuer: String.t(), period: pos_integer() }
TOTP key information returned from read operations.
@type key_name() :: String.t()
TOTP key name. Must be a non-empty string with valid characters.
@type list_keys_result() :: {:ok, [String.t()]} | {:error, Vaultx.Base.Error.t()}
Result of a key list operation.
@type operation_opts() :: [ mount_path: String.t(), timeout: pos_integer(), retry_attempts: non_neg_integer() ]
Options for TOTP secrets engine operations.
@type read_key_result() :: {:ok, key_info()} | {:error, Vaultx.Base.Error.t()}
Result of a key read operation.
@type totp_code() :: %{code: String.t()}
Generated TOTP code.
@type validate_code_result() :: {:ok, validation_result()} | {:error, Vaultx.Base.Error.t()}
Result of a code validation operation.
@type validation_result() :: %{valid: boolean()}
TOTP code validation result.
Callbacks
@callback create_key(key_name(), key_config(), operation_opts()) :: create_key_result()
Create or update a TOTP key.
Creates a new TOTP key definition that can be used to generate time-based one-time passwords. Supports both generated keys and imported keys from external sources.
Parameters
name- Key nameconfig- Key configuration parametersopts- Operation options
Returns
{:ok, response}- Successfully created key (may include QR code){:error, error}- Failed to create key
Examples
# Generate a new key
config = %{
generate: true,
issuer: "MyApp",
account_name: "user@example.com"
}
{:ok, response} = MyTOTP.create_key("user-key", config, [])
# Import an existing key
config = %{
url: "otpauth://totp/Google:test@gmail.com?secret=Y64VEVMBTSXCYIWRSHRNDZW62MPGVU2G&issuer=Google"
}
{:ok, _} = MyTOTP.create_key("imported-key", config, [])@callback delete_key(key_name(), operation_opts()) :: delete_key_result()
Delete a TOTP key.
Parameters
name- Key name to deleteopts- Operation options
Returns
:ok- Successfully deleted key{:error, error}- Failed to delete key
Examples
:ok = MyTOTP.delete_key("old-key", [])@callback generate_code(key_name(), operation_opts()) :: generate_code_result()
Generate a TOTP code for a key.
Parameters
name- Key name to generate code foropts- Operation options
Returns
{:ok, code}- Successfully generated code{:error, error}- Failed to generate code
Examples
{:ok, code} = MyTOTP.generate_code("user-key", [])@callback list_keys(operation_opts()) :: list_keys_result()
List all configured TOTP keys.
Parameters
opts- Operation options
Returns
{:ok, keys}- Successfully listed keys{:error, error}- Failed to list keys
Examples
{:ok, keys} = MyTOTP.list_keys([])@callback read_key(key_name(), operation_opts()) :: read_key_result()
Read a TOTP key configuration.
Parameters
name- Key name to readopts- Operation options
Returns
{:ok, key_info}- Successfully read key information{:error, error}- Failed to read key
Examples
{:ok, info} = MyTOTP.read_key("user-key", [])@callback validate_code(key_name(), String.t(), operation_opts()) :: validate_code_result()
Validate a TOTP code against a key.
Parameters
name- Key name to validate againstcode- TOTP code to validateopts- Operation options
Returns
{:ok, result}- Successfully validated code{:error, error}- Failed to validate code
Examples
{:ok, result} = MyTOTP.validate_code("user-key", "123456", [])