apiculture
Apiculture - cryptographically secure API-key generation for Gleam.
The top-level module provides the v0.3.0 API for generating, importing, parsing, inspecting, and verifying structured API keys. Start here for ordinary application use; the lower-level modules are available when a more specialized encoding, alphabet, or checksum workflow is needed.
Types
A validated character repertoire for direct random character sampling.
pub type Alphabet =
alphabet.AlphabetA checksum algorithm used to validate key content.
pub type Checksum =
checksum.ChecksumA byte-to-text encoding used for key content and checksum sections.
pub type Encoding =
encoding.EncodingErrors returned by key generation, parsing, encoding, and validation.
pub type Error =
error.ErrorA finalized API key, including its serialized value and inspectable sections.
pub type Key =
key.KeyA chainable plan for generating or formatting a key.
A KeyConfig is not a key. Finish it with key_generate, key_from_bytes,
or one of the configured UUID/ULID import functions.
pub type KeyConfig =
key.KeyConfigThe parse-relevant shape of a serialized key.
Use KeyFormat with key_parse_with_format; generation intent is kept in
KeyConfig because it cannot be recovered from a serialized value.
pub type KeyFormat =
key.KeyFormatThe prefix, content, and checksum sections of a finalized key.
pub type KeySections =
key.KeySectionsValues
pub fn alphabet_characters(
alphabet: alphabet.Alphabet,
) -> List(String)Returns the graphemes in a validated alphabet.
pub fn alphabet_size(alphabet: alphabet.Alphabet) -> IntReturns the number of graphemes in an alphabet.
pub fn base32_crockford() -> encoding.EncodingReturns Crockford Base32 encoding.
pub fn base32_rfc_unpadded() -> encoding.EncodingReturns unpadded RFC 4648 Base32 encoding.
pub fn bytes_from_ulid(
input: String,
) -> Result(BitArray, error.Error)Parses a ULID into its canonical 16 bytes.
pub fn bytes_from_uuid(
input: String,
) -> Result(BitArray, error.Error)Parses a UUID into its canonical 16 bytes.
pub fn checksum_format(
csum: checksum.Checksum,
bytes: BitArray,
format_with: fn(BitArray) -> String,
) -> StringFormats a checksum using a caller-provided byte encoding function.
pub fn checksum_mismatch_error() -> error.ErrorReturns the error for a checksum that does not match its content.
pub fn checksum_verify(
csum: checksum.Checksum,
bytes: BitArray,
expected: BitArray,
) -> BoolVerifies raw bytes against an expected checksum.
pub fn crc32() -> checksum.ChecksumReturns the CRC32 checksum algorithm used by the default key format.
pub fn default_generate() -> Result(key.Key, error.Error)Compatibility alias for generating a v0.3.0 default key.
Prefer key_new() in new code. This function returns the same structured
sk_<content>_crc32_<checksum> format.
pub fn default_prefixed(
prefix: String,
) -> Result(key.Key, error.Error)Generates a v0.3.0 structured key with a custom prefix.
The format is <prefix>_<content>_crc32_<checksum>.
The prefix should be a short semantic identifier (e.g., “sk”, “token”, “key”).
pub fn duplicate_characters_error() -> error.ErrorReturns the error for a custom alphabet containing duplicate characters.
pub fn empty_alphabet_error() -> error.ErrorReturns the error for an empty custom alphabet.
pub fn encoding_decode(
enc: encoding.Encoding,
input: String,
) -> Result(BitArray, error.Error)Decodes a string with an apiculture encoding.
pub fn encoding_encode(
enc: encoding.Encoding,
bytes: BitArray,
) -> StringEncodes bytes with an apiculture encoding.
pub fn encoding_name(enc: encoding.Encoding) -> StringReturns the multibase name of an encoding.
pub fn encoding_uses_padding(enc: encoding.Encoding) -> BoolReports whether an encoding uses padding.
pub fn invalid_byte_count_error() -> error.ErrorReturns the error for an invalid or incomplete byte/character count.
pub fn invalid_encoding_error() -> error.ErrorReturns the error for an invalid encoding configuration.
pub fn key_bytes(k: key.Key) -> BitArrayReturns the raw content bytes of a finalized key.
This is a compatibility alias for key_content_bytes.
pub fn key_checksum_byte_count(k: key.Key) -> IntReturns the checksum byte count, or 0 when no checksum is present.
pub fn key_checksum_bytes(k: key.Key) -> option.Option(BitArray)Returns the optional raw checksum bytes.
pub fn key_checksum_char_count(k: key.Key) -> option.Option(Int)Returns the encoded checksum character count, when present.
pub fn key_checksum_name(k: key.Key) -> option.Option(String)Returns the optional lowercase checksum algorithm name.
pub fn key_checksum_value(k: key.Key) -> option.Option(String)Returns the optional encoded checksum section.
pub fn key_config_is_ready(config: key.KeyConfig) -> BoolReports whether a configuration contains one valid content-generation mode.
pub fn key_content_byte_count(k: key.Key) -> IntReturns the number of raw content bytes.
pub fn key_content_bytes(k: key.Key) -> BitArrayReturns the raw bytes represented by the content section.
pub fn key_content_char_count(k: key.Key) -> IntReturns the number of characters in the encoded content section.
pub fn key_content_value(k: key.Key) -> StringReturns the encoded content section without prefix or checksum sections.
pub fn key_default_format() -> key.KeyFormatReturns the parse format corresponding to the v0.3.0 default.
pub fn key_disable_checksum(
config: key.KeyConfig,
) -> key.KeyConfigRemoves both the checksum and its serialized name.
pub fn key_disable_checksum_name(
config: key.KeyConfig,
) -> key.KeyConfigRemoves the checksum name while retaining the checksum.
pub fn key_disable_prefix(config: key.KeyConfig) -> key.KeyConfigRemoves the prefix from a key configuration.
pub fn key_format_with_checksum(
format: key.KeyFormat,
checksum: checksum.Checksum,
) -> key.KeyFormatChanges the expected checksum algorithm in a parser format.
pub fn key_format_with_checksum_bytes(
format: key.KeyFormat,
count: Int,
) -> key.KeyFormatChanges the expected checksum byte count in a parser format.
pub fn key_format_with_content_bytes(
format: key.KeyFormat,
count: Int,
) -> key.KeyFormatChanges the expected content byte count in a parser format.
pub fn key_format_with_encoding(
format: key.KeyFormat,
encoding: encoding.Encoding,
) -> key.KeyFormatChanges the expected encoding in a parser format.
pub fn key_format_with_prefix(
format: key.KeyFormat,
prefix: String,
) -> key.KeyFormatChanges the expected prefix in a parser format.
pub fn key_format_with_separator(
format: key.KeyFormat,
separator: String,
) -> key.KeyFormatChanges the expected separator in a parser format.
pub fn key_format_without_checksum(
format: key.KeyFormat,
) -> key.KeyFormatRemoves the expected checksum from a parser format.
pub fn key_format_without_checksum_name(
format: key.KeyFormat,
) -> key.KeyFormatRemoves the expected checksum name from a parser format.
pub fn key_format_without_prefix(
format: key.KeyFormat,
) -> key.KeyFormatRemoves the expected prefix from a parser format.
pub fn key_from_bytes(
config: key.KeyConfig,
bytes: BitArray,
) -> Result(key.Key, error.Error)Formats existing bytes using a key configuration.
This is the terminal step for parse-then-format UUID and ULID workflows.
pub fn key_from_ulid(
input: String,
) -> Result(key.Key, error.Error)Imports a ULID using the v0.3.0 default key format.
pub fn key_from_ulid_with_config(
config: key.KeyConfig,
input: String,
) -> Result(key.Key, error.Error)Imports a ULID and formats it with a supplied configuration.
pub fn key_from_uuid(
input: String,
) -> Result(key.Key, error.Error)Imports a UUID using the v0.3.0 default key format.
This is a terminal operation. Use bytes_from_uuid followed by
key_from_bytes when the formatting pipeline needs to remain explicit.
pub fn key_from_uuid_with_config(
config: key.KeyConfig,
input: String,
) -> Result(key.Key, error.Error)Imports a UUID and formats it with a supplied configuration.
pub fn key_generate(
config: key.KeyConfig,
) -> Result(key.Key, error.Error)Finalizes a random-generation configuration as a Key.
This is a terminal operation. It generates fresh content according to the selected mode and retains the rendered sections for later inspection.
pub fn key_has_checksum(k: key.Key) -> BoolReports whether the key has a checksum.
pub fn key_new() -> Result(key.Key, error.Error)Generates one key using the v0.3.0 default format.
The default is sk_<content>_crc32_<checksum> with 16 random bytes encoded
as Base62 and a four-byte CRC32 checksum.
pub fn key_new_as_config() -> key.KeyConfigReturns a ready-to-generate configuration containing the default settings.
Use the key_with_* and key_disable_* functions to customize it.
Examples
let assert Ok(key) =
key_new_as_config()
|> key_with_prefix("partner")
|> key_generate
pub fn key_new_as_string() -> Result(String, error.Error)Generates and serializes one key using the v0.3.0 default format.
Examples
let assert Ok(value) = key_new_as_string()
pub fn key_parse(input: String) -> Result(key.Key, error.Error)Parses and verifies a key in the strict default serialized format.
A successful result has canonical Base62 content, the expected sk prefix,
16 content bytes, and a matching four-byte CRC32 checksum.
pub fn key_parse_with_format(
input: String,
format: key.KeyFormat,
) -> Result(key.Key, error.Error)Parses and verifies a key using an explicitly supplied format.
pub fn key_prefix_value(k: key.Key) -> option.Option(String)Returns the optional serialized prefix.
pub fn key_sections(k: key.Key) -> key.KeySectionsReturns all serialized and raw key sections as one value.
pub fn key_separator_value(k: key.Key) -> option.Option(String)Returns the optional structural separator.
pub fn key_to_string(k: key.Key) -> StringReturns the serialized value of a finalized key.
pub fn key_value(k: key.Key) -> StringReturns the serialized value of a finalized key.
Prefer key_to_string in pipelines; this name remains for compatibility.
pub fn key_verify_checksum(k: key.Key) -> BoolVerifies a key with the default CRC32 algorithm.
pub fn key_verify_checksum_with_algo(
k: key.Key,
csum: checksum.Checksum,
) -> BoolVerifies a key with an explicitly supplied checksum algorithm.
pub fn key_with_alphabet(
config: key.KeyConfig,
alphabet: alphabet.Alphabet,
) -> key.KeyConfigSets the alphabet used by direct character sampling.
pub fn key_with_checksum(
config: key.KeyConfig,
checksum: checksum.Checksum,
) -> key.KeyConfigSets the checksum algorithm and serialized algorithm name.
pub fn key_with_checksum_bytes(
config: key.KeyConfig,
count: Int,
) -> key.KeyConfigSets the number of checksum bytes retained in the key.
pub fn key_with_encoding(
config: key.KeyConfig,
encoding: encoding.Encoding,
) -> key.KeyConfigSets the encoding used for content and checksum sections.
pub fn key_with_prefix(
config: key.KeyConfig,
prefix: String,
) -> key.KeyConfigSets the serialized key prefix.
pub fn key_with_random_bytes(
config: key.KeyConfig,
count: Int,
) -> key.KeyConfigSelects secure random byte generation with the given byte count.
pub fn key_with_random_chars(
config: key.KeyConfig,
count: Int,
) -> key.KeyConfigSelects direct alphabet sampling with the given character count.
Pair this with key_with_alphabet; it is distinct from generating random
bytes and then encoding them.
pub fn key_with_separator(
config: key.KeyConfig,
separator: String,
) -> key.KeyConfigSets the separator used at every structural boundary.
pub fn malformed_input_error() -> error.ErrorReturns the error for malformed encoded, UUID, ULID, or serialized input.
pub fn new_alphabet(
chars: String,
) -> Result(alphabet.Alphabet, error.Error)Creates a validated custom alphabet for direct character sampling.
The alphabet must contain at least two unique graphemes.
pub fn secure_random_unavailable_error() -> error.ErrorReturns the error raised when secure randomness is unavailable.
pub fn single_character_alphabet_error() -> error.ErrorReturns the error for a one-character custom alphabet.