### Full Google Authenticator Setup Example

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/_autodocs/api-reference/GoogleAuthenticator.md

A comprehensive example demonstrating the complete setup process for using Google Authenticator. This includes generating a secret, creating a QR code URI for app enrollment, and validating a user-entered code.

```kotlin
import dev.turingcomplete.kotlinonetimepassword.GoogleAuthenticator
import org.apache.commons.codec.binary.Base32
import java.util.Date

// 1. Generate a random secret (first time setup)
val base32Secret = GoogleAuthenticator.createRandomSecretAsByteArray()
println("Secret to store: ${String(base32Secret)}")

// 2. Create QR code URI (scan with Google Authenticator)
val qrCodeUri = GoogleAuthenticator(base32Secret)
    .otpAuthUriBuilder()
    .label("alice@company.com", "Company")
    .issuer("Company")
    .buildToString()
println("QR code URI: $qrCodeUri")

// 3. Later: Validate user's code during login
val google = GoogleAuthenticator(base32Secret)
val userCode = "123456"  // User enters this from authenticator app
val isValid = google.isValid(userCode)
println("Code is valid: $isValid")
```

--------------------------------

### Standard Secure Configuration

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/_autodocs/api-reference/HmacOneTimePasswordConfig.md

Example of creating a standard, secure HmacOneTimePasswordConfig with 6 digits and SHA1 algorithm.

```kotlin
import dev.turingcomplete.kotlinonetimepassword.HmacOneTimePasswordConfig
import dev.turingcomplete.kotlinonetimepassword.HmacAlgorithm

val config = HmacOneTimePasswordConfig(
    codeDigits = 6,
    hmacAlgorithm = HmacAlgorithm.SHA1
)
```

--------------------------------

### TOTP Setup

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/_autodocs/api-reference/OtpAuthUriBuilder.md

Demonstrates how to set up a Time-based One-Time Password (TOTP) URI. This includes specifying the secret, label, issuer, algorithm, digits, and period.

```APIDOC
## TOTP Setup

### Description

Constructs a Time-based One-Time Password (TOTP) URI.

### Method

`OtpAuthUriBuilder.forTotp(secret: ByteArray)`

### Parameters

#### Path Parameters

None

#### Query Parameters

None

#### Request Body

None

### Builder Methods

- `label(name: String, type: String)`: Sets the user's account name and account type.
- `issuer(issuer: String)`: Sets the issuer name.
- `algorithm(algorithm: HmacAlgorithm)`: Sets the HMAC algorithm.
- `digits(digits: Int)`: Sets the number of digits in the OTP.
- `period(period: Long, unit: TimeUnit)`: Sets the time period for the OTP.

### Build

- `buildToString()`: Builds the OTP URI as a String.

### Example

```kotlin
import dev.turingcomplete.kotlinonetimepassword.OtpAuthUriBuilder
import dev.turingcomplete.kotlinonetimepassword.HmacAlgorithm
import org.apache.commons.codec.binary.Base32
import java.util.concurrent.TimeUnit

val secret = Base32().encode("MySharedSecret".toByteArray())

val uri = OtpAuthUriBuilder.forTotp(secret)
    .label("alice@company.com", "Company")
    .issuer("Company")
    .algorithm(HmacAlgorithm.SHA1)
    .digits(6)
    .period(30, TimeUnit.SECONDS)
    .buildToString()

println(uri)
// otpauth://totp/Company:alice%40company.com?algorithm=SHA1&digits=6&period=30&issuer=Company&secret=...
```
```

--------------------------------

### HOTP Setup

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/_autodocs/api-reference/OtpAuthUriBuilder.md

Demonstrates how to set up a Hash-based Message Authentication Code (HOTP) URI. This includes specifying the initial counter, secret, label, issuer, and algorithm.

```APIDOC
## HOTP Setup

### Description

Constructs a Hash-based Message Authentication Code (HOTP) URI.

### Method

`OtpAuthUriBuilder.forHotp(counter: Long, secret: ByteArray)`

### Parameters

#### Path Parameters

None

#### Query Parameters

None

#### Request Body

None

### Builder Methods

- `label(name: String, type: String)`: Sets the user's account name and account type.
- `issuer(issuer: String)`: Sets the issuer name.
- `algorithm(algorithm: HmacAlgorithm)`: Sets the HMAC algorithm.

### Build

- `buildToString()`: Builds the OTP URI as a String.

### Example

```kotlin
val uri = OtpAuthUriBuilder.forHotp(0, secret)
    .label("bob@example.com", "Example")
    .issuer("Example")
    .algorithm(HmacAlgorithm.SHA256)
    .buildToString()
```
```

--------------------------------

### HOTP URI Configuration Example

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/_autodocs/configuration.md

Configures parameters for a Hash-based One-Time Password (HOTP) URI using OtpAuthUriBuilder. This is used for generating QR codes for counter-based OTPs.

```kotlin
val builder = OtpAuthUriBuilder.forHotp(0, base32Secret)
    .label("alice@example.com", "Example Corp")
    .issuer("Example Corp")
    .algorithm(HmacAlgorithm.SHA256)
    .digits(8)

val uri = builder.buildToString()
//otpauth://hotp/Example%20Corp:alice%40example.com?counter=0&algorithm=SHA256&digits=8&issuer=Example%20Corp&secret=...
```

--------------------------------

### Build OTPAuth URI for QR Codes (TOTP)

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/README.md

Constructs a Key URI Format string for embedding in QR codes, facilitating easy OTP account setup. This example specifically configures a TOTP generator with custom digits and labels.

```kotlin
OtpAuthUriBuilder.forTotp(Base32().encode("secret".toByteArray()))
  .label("John", "Company")
  .issuer("Company")
  .digits(8)
  .buildToString()
```

--------------------------------

### Time Step Calculation Example

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/_autodocs/api-reference/TimeBasedOneTimePasswordConfig.md

Illustrates how timestamps are mapped to a counter based on a 30-second time step. This is crucial for understanding TOTP code generation.

```kotlin
// Given 30-second time step:
// Timestamps 0–29999 ms 
// Timestamps 30000–59999 ms 
// Timestamps 60000–89999 ms 
```

--------------------------------

### timeslotStart

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/_autodocs/api-reference/TimeBasedOneTimePasswordGenerator.md

Calculates the start timestamp of a time slot represented by a TOTP counter.

```APIDOC
## timeslotStart

### Description
Calculates the start timestamp of a time slot represented by a TOTP counter. This is the inverse operation of `counter()`.

### Method
`fun timeslotStart(counter: Long): Long`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **counter** (Long) - Required - The counter representing a time slot.

### Returns
- **Long** - The Unix timestamp in milliseconds where the time slot starts.

### Behavior
Calculation: `counter * timeStepInMillis`.

### Example
```kotlin
val config = TimeBasedOneTimePasswordConfig(30, TimeUnit.SECONDS, 6, HmacAlgorithm.SHA1)
val generator = TimeBasedOneTimePasswordGenerator("Secret".toByteArray(), config)

val now = System.currentTimeMillis()
val counter = generator.counter(now)

// Calculate time slot boundaries
val slotStart = generator.timeslotStart(counter)
val slotEnd = generator.timeslotStart(counter + 1) - 1

// Milliseconds until next code
val millisUntilNextCode = slotEnd - now + 1
println("Current code expires in: ${millisUntilNextCode}ms")
```
```

--------------------------------

### Generate HOTP with HmacOneTimePasswordGenerator

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/_autodocs/api-reference/HmacAlgorithm.md

Example of creating an HOTP generator using HmacAlgorithm.SHA1 for maximum compatibility. Requires importing necessary classes.

```kotlin
import dev.turingcomplete.kotlinonetimepassword.HmacOneTimePasswordGenerator
import dev.turingcomplete.kotlinonetimepassword.HmacOneTimePasswordConfig
import dev.turingcomplete.kotlinonetimepassword.HmacAlgorithm

// Create HOTP generator using SHA1 (most compatible)
val config = HmacOneTimePasswordConfig(
    codeDigits = 6,
    hmacAlgorithm = HmacAlgorithm.SHA1
)
val generator = HmacOneTimePasswordGenerator("SharedSecret".toByteArray(), config)
val code = generator.generate(counter = 0)
```

--------------------------------

### HOTP Challenge-Response Flow

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/_autodocs/api-reference/HmacOneTimePasswordGenerator.md

Demonstrates the server-side setup and client-side generation/validation of an HOTP code within a challenge-response pattern. Requires pre-shared secret and configuration.

```kotlin
val secret = "SharedSecretFromProvisioning".toByteArray()
val config = HmacOneTimePasswordConfig(6, HmacAlgorithm.SHA1)
val generator = HmacOneTimePasswordGenerator(secret, config)

// User process
val userCounter = 42L  // Server sends this challenge to user
val userCode = generator.generate(userCounter)  // User generates code
println("Generated code: $userCode")

// Server validation
val isValid = generator.isValid(userCode, userCounter)
println("Code is valid: $isValid")
```

--------------------------------

### TOTP URI Configuration Example

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/_autodocs/configuration.md

Configures parameters for a Time-Based One-Time Password (TOTP) URI using OtpAuthUriBuilder. This is typically used to generate QR codes for authenticator apps.

```kotlin
import dev.turingcomplete.kotlinonetimepassword.OtpAuthUriBuilder
import dev.turingcomplete.kotlinonetimepassword.HmacAlgorithm
import java.util.concurrent.TimeUnit

val builder = OtpAuthUriBuilder.forTotp(base32Secret)
    .label("user@example.com", "My Company")
    .issuer("My Company")
    .algorithm(HmacAlgorithm.SHA1)
    .digits(6)
    .period(30, TimeUnit.SECONDS)

val uri = builder.buildToString()
//otpauth://totp/My%20Company:user%40example.com?algorithm=SHA1&digits=6&period=30&issuer=My%20Company&secret=...
```

--------------------------------

### Legacy Configuration with Short Codes

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/_autodocs/api-reference/HmacOneTimePasswordConfig.md

Example of creating a legacy HmacOneTimePasswordConfig with 4 digits, allowing insecure configuration for test vectors or insecure deployments.

```kotlin
// For reproducing legacy test vectors or interoperating with insecure deployments
val legacyConfig = HmacOneTimePasswordConfig(
    codeDigits = 4,
    hmacAlgorithm = HmacAlgorithm.SHA1,
    allowInsecureConfiguration = true
)
```

--------------------------------

### Configure TOTP with HmacAlgorithm.SHA256

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/_autodocs/api-reference/HmacAlgorithm.md

Example of configuring a TOTP generator with HmacAlgorithm.SHA256 for enhanced security. Ensure correct time step and units are set.

```kotlin
import dev.turingcomplete.kotlinonetimepassword.TimeBasedOneTimePasswordGenerator
import dev.turingcomplete.kotlinonetimepassword.TimeBasedOneTimePasswordConfig
import dev.turingcomplete.kotlinonetimepassword.HmacAlgorithm
import java.util.concurrent.TimeUnit

// Create TOTP generator with SHA256
val config = TimeBasedOneTimePasswordConfig(
    timeStep = 30,
    timeStepUnit = TimeUnit.SECONDS,
    codeDigits = 6,
    hmacAlgorithm = HmacAlgorithm.SHA256
)
val generator = TimeBasedOneTimePasswordGenerator("SharedSecret".toByteArray(), config)
val code = generator.generate()
```

--------------------------------

### Maximum Security Configuration with SHA512

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/_autodocs/api-reference/HmacOneTimePasswordConfig.md

Example of creating an HmacOneTimePasswordConfig for maximum security using 8 digits and the SHA512 algorithm.

```kotlin
val maxSecurityConfig = HmacOneTimePasswordConfig(
    codeDigits = 8,
    hmacAlgorithm = HmacAlgorithm.SHA512
)
```

--------------------------------

### Generated Code String Example

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/_autodocs/types.md

Illustrates the return type of the `generate` method, which is always a `String`. This string is zero-padded to the specified `codeDigits` length, and leading zeroes are significant.

```kotlin
val code: String = generator.generate(...)
```

--------------------------------

### Zero-Digit Codes for Testing

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/_autodocs/api-reference/HmacOneTimePasswordConfig.md

Example of creating an HmacOneTimePasswordConfig with 0 digits, intended only for tests or legacy compatibility, requiring allowInsecureConfiguration to be true.

```kotlin
// Creates empty string codes, intended only for tests or legacy compatibility
val testConfig = HmacOneTimePasswordConfig(
    codeDigits = 0,
    hmacAlgorithm = HmacAlgorithm.SHA1,
    allowInsecureConfiguration = true
)
```

--------------------------------

### Calculate Time Slot Information

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/_autodocs/api-reference/TimeBasedOneTimePasswordGenerator.md

Shows how to calculate the current time slot, the start of the next time slot, and the remaining validity period for a TOTP code. This is useful for understanding code expiry.

```kotlin
val config = TimeBasedOneTimePasswordConfig(30, TimeUnit.SECONDS, 6, HmacAlgorithm.SHA1)
val generator = TimeBasedOneTimePasswordGenerator("Secret".toByteArray(), config)

val timestamp = System.currentTimeMillis()
val counter = generator.counter(timestamp)

// Time slot boundaries
val slotStartMs = generator.timeslotStart(counter)
val nextSlotStartMs = generator.timeslotStart(counter + 1)
val slotDurationMs = nextSlotStartMs - slotStartMs

// How long current code remains valid
val msUntilExpiry = nextSlotStartMs - timestamp
println("Code expires in: ${msUntilExpiry}ms")
```

--------------------------------

### OTP Generator Example with Multiple Date Representations

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/_autodocs/types.md

Demonstrates generating one-time passwords using `TimeBasedOneTimePasswordGenerator` with different date/time representations: `Long` (timestamp), `java.util.Date`, and `java.time.Instant`. The configuration includes the time step, time step unit, code digits, and HMAC algorithm.

```kotlin
import dev.turingcomplete.kotlinonetimepassword.TimeBasedOneTimePasswordGenerator
import dev.turingcomplete.kotlinonetimepassword.TimeBasedOneTimePasswordConfig
import dev.turingcomplete.kotlinonetimepassword.HmacAlgorithm
import java.util.Date
import java.time.Instant
import java.util.concurrent.TimeUnit

val config = TimeBasedOneTimePasswordConfig(30, TimeUnit.SECONDS, 6, HmacAlgorithm.SHA1)
val generator = TimeBasedOneTimePasswordGenerator("Secret".toByteArray(), config)

// All three representations work
val code1 = generator.generate()  // Current system time (Long)
val code2 = generator.generate(Date())  // Date object
val code3 = generator.generate(Instant.now())  // Instant object
val code4 = generator.generate(1640000000000L)  // Explicit timestamp
```

--------------------------------

### Full Provisioning Workflow for Google Authenticator

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/_autodocs/api-reference/RandomSecretGenerator.md

Illustrates the complete process of generating a secret, encoding it to Base32, creating a provisioning URI for a QR code, and later validating a user-entered code.

```kotlin
import dev.turingcomplete.kotlinonetimepassword.RandomSecretGenerator
import dev.turingcomplete.kotlinonetimepassword.GoogleAuthenticator
import org.apache.commons.codec.binary.Base32

// 1. Server generates random secret for user
val secretGenerator = RandomSecretGenerator()
val plainSecret = secretGenerator.createRandomSecret(10)  // 10-byte secret

// 2. Encode to Base32 for QR code
val base32Secret = Base32().encode(plainSecret)
val base32String = String(base32Secret)
println("Store this secret safely: $base32String")

// 3. Create provisioning URI with QR code
val google = GoogleAuthenticator(base32Secret)
val qrUri = google.otpAuthUriBuilder()
    .label("user@example.com", "MyService")
    .issuer("MyService")
    .buildToString()
println("QR code URI: $qrUri")

// 4. Later: validate user's code
val userCode = "123456"  // User scans QR and enters code
val isValid = google.isValid(userCode)
println("Code valid: $isValid")
```

--------------------------------

### Publish Public Key to Keyserver

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/docs/release.md

Send your public GPG key to a keyserver, such as `keyserver.ubuntu.com`, so Sonatype can validate signatures.

```shell
gpg --keyserver keyserver.ubuntu.com --send-keys <key-id>
```

--------------------------------

### Run Local Publish and Tag Together

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/docs/release.md

Execute both the local publish and tag steps in a single command for a streamlined release process.

```shell
task release VERSION=<version>
```

--------------------------------

### From Generator with Preconfigured Parameters

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/_autodocs/api-reference/OtpAuthUriBuilder.md

Shows how to obtain an `OtpAuthUriBuilder` from a preconfigured generator like `GoogleAuthenticator` and customize the URI.

```APIDOC
## From Generator with Preconfigured Parameters

### Description

Obtains an `OtpAuthUriBuilder` from a generator (e.g., `GoogleAuthenticator`) and customizes the OTP URI.

### Method

`generator.otpAuthUriBuilder()`

### Parameters

#### Path Parameters

None

#### Query Parameters

None

#### Request Body

None

### Builder Methods

- `label(name: String, type: String)`: Sets the user's account name and account type.
- `issuer(issuer: String)`: Sets the issuer name.

### Build

- `buildToString()`: Builds the OTP URI as a String.

### Example

```kotlin
import dev.turingcomplete.kotlinonetimepassword.GoogleAuthenticator

val google = GoogleAuthenticator("JBSWY3DPEBLW64TMMQ=====".toByteArray())

val uri = google.otpAuthUriBuilder()
    .label("user@example.com", "MyApp")
    .issuer("MyApp")
    .buildToString()
```
```

--------------------------------

### buildToUri

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/_autodocs/api-reference/OtpAuthUriBuilder.md

Builds and returns the complete OTP Auth URI as a `java.net.URI` object. Similar to `buildToString`, this involves a string representation that includes the secret.

```APIDOC
## buildToUri

### Description
Builds the final OTP Auth URI as a `java.net.URI`.

### Method
```kotlin
fun buildToUri(): URI
```

### Parameters
None

### Returns
- **URI** - The complete OTP Auth URI as a URI object.

**Warning:** Creating a URI requires a string representation containing the secret. Use `buildToByteArray()` to avoid keeping secrets in immutable JVM strings.
```

--------------------------------

### forTotp Static Factory Method

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/_autodocs/api-reference/OtpAuthUriBuilder.md

Creates a builder for a TOTP OTP Auth URI.

```APIDOC
## forTotp

### Description
Creates a builder for a TOTP OTP Auth URI.

### Method
`companion object` static factory method

### Endpoint
N/A (Static factory method)

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- None

### Parameters
- **base32Secret** (ByteArray) - Required - The secret as Base32-encoded bytes.

### Returns
An `OtpAuthUriBuilder.Totp` instance.

### Throws
- `IllegalArgumentException` if `base32Secret` is not valid Base32.

### Example
```kotlin
import dev.turingcomplete.kotlinonetimepassword.OtpAuthUriBuilder
import org.apache.commons.codec.binary.Base32

val secret = Base32().encode("MySecret".toByteArray())
val builder = OtpAuthUriBuilder.forTotp(secret)
```
```

--------------------------------

### Legacy Zero Time Step Configuration (Test Only)

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/_autodocs/api-reference/TimeBasedOneTimePasswordConfig.md

This snippet creates a static counter configuration with a zero time step. It is not recommended for production use and requires `allowInsecureConfiguration` to be set to true.

```kotlin
// Creates a static counter (not recommended for production)
val legacyConfig = TimeBasedOneTimePasswordConfig(
    timeStep = 0,
    timeStepUnit = TimeUnit.SECONDS,
    codeDigits = 6,
    hmacAlgorithm = HmacAlgorithm.SHA1,
    allowInsecureConfiguration = true
)
```

--------------------------------

### buildToString

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/_autodocs/api-reference/OtpAuthUriBuilder.md

Builds and returns the complete OTP Auth URI as a String. Be cautious as this string will contain the shared secret.

```APIDOC
## buildToString

### Description
Builds the final OTP Auth URI as a String.

### Method
```kotlin
fun buildToString(): String
```

### Parameters
None

### Returns
- **String** - The complete OTP Auth URI as a String.

**Warning:** The returned string contains the shared secret. Use `buildToByteArray()` to avoid keeping secrets in immutable JVM strings.
```

--------------------------------

### gradle.properties Configuration

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/docs/release.md

Configure the `signingInMemoryKey` and `signingInMemoryKeyPassword` properties in `~/.gradle/gradle.properties`. The private key must be on a single line.

```properties
signingInMemoryKey=-----BEGIN PGP PRIVATE KEY BLOCK-----\n...\n-----END PGP PRIVATE KEY BLOCK-----\nsigningInMemoryKeyPassword=<gpg-key-password>
```

--------------------------------

### Calculate Time Slot Boundaries

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/_autodocs/api-reference/TimeBasedOneTimePasswordGenerator.md

Calculates the start timestamp of a time slot using a counter. This is useful for determining when the current TOTP code expires. The calculation is `counter * timeStepInMillis`.

```kotlin
val config = TimeBasedOneTimePasswordConfig(30, TimeUnit.SECONDS, 6, HmacAlgorithm.SHA1)
val generator = TimeBasedOneOneTimePasswordGenerator("Secret".toByteArray(), config)

val now = System.currentTimeMillis()
val counter = generator.counter(now)

// Calculate time slot boundaries
val slotStart = generator.timeslotStart(counter)
val slotEnd = generator.timeslotStart(counter + 1) - 1

// Milliseconds until next code
val millisUntilNextCode = slotEnd - now + 1
println("Current code expires in: ${millisUntilNextCode}ms")
```

--------------------------------

### Simulate Google Authenticator on Command Line

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/README.md

This code snippet simulates the Google Authenticator behavior by printing a valid OTP every second for a given Base32 encoded secret. It uses a fixed timestamp for generation.

```kotlin
fun main() {
  val base32Secret = "K6IPBHCQTVLCZDM2"

  Timer().schedule(object: TimerTask() {
    override fun run() {
      val timestamp = Date(System.currentTimeMillis())
      val code = GoogleAuthenticator(base32Secret).generate(timestamp)
      println("${SimpleDateFormat("HH:mm:ss").format(timestamp)}: $code")
    }
  }, 0, 1000)
}
```

--------------------------------

### GoogleAuthenticator Secret Creation

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/_autodocs/configuration.md

Examples for creating secrets for Google Authenticator. Supports creating from a Base32 secret, generating a new random secret (historical Google size), or generating a stronger random secret.

```kotlin
// Create from Base32 secret
val base32Secret = "JBSWY3DPEBLW64TMMQ======
```

```kotlin
val google = GoogleAuthenticator(base32Secret)

// Generate new secret (historical Google size)
val secret = GoogleAuthenticator.createRandomSecretAsByteArray()

// Generate new secret (stronger)
val secret = GoogleAuthenticator.createSecureRandomSecretAsByteArray()
```

--------------------------------

### Calculate TOTP Validity Period

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/README.md

Calculate the start and end times of the current TOTP time slot, and determine how many milliseconds the current code remains valid. This requires generating the TOTP and its counter first.

```kotlin
val instant = java.time.Instant.ofEpochSecond(1622234248L)
val timestamp = instant.toEpochMilli()
val totp = timeBasedOneTimePasswordGenerator.generate(timestamp)
val counter = timeBasedOneTimePasswordGenerator.counter()
val startEpochMillis = timeBasedOneTimePasswordGenerator.timeslotStart(counter)
// The start of the next time slot minus 1 ms
val endEpochMillis = timeBasedOneTimePasswordGenerator.timeslotStart(counter + 1) - 1
// The number of milliseconds the current TOTP remains valid
val millisValid = endEpochMillis - timestamp
```

--------------------------------

### forHotp Static Factory Method

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/_autodocs/api-reference/OtpAuthUriBuilder.md

Creates a builder for an HOTP OTP Auth URI.

```APIDOC
## forHotp

### Description
Creates a builder for an HOTP OTP Auth URI.

### Method
`companion object` static factory method

### Endpoint
N/A (Static factory method)

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- None

### Parameters
- **initialCounter** (Long) - Required - The initial counter value for HOTP. Must be non-negative.
- **base32Secret** (ByteArray) - Required - The secret as Base32-encoded bytes.

### Returns
An `OtpAuthUriBuilder.Hotp` instance.

### Throws
- `IllegalArgumentException` if:
  - `initialCounter` is negative
  - `base32Secret` is not valid Base32

### Example
```kotlin
val secret = Base32().encode("MySecret".toByteArray())
val builder = OtpAuthUriBuilder.forHotp(0, secret)
```
```

--------------------------------

### Code Validation Boolean Example

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/_autodocs/types.md

Shows the return type of the `isValid` method, which is a `Boolean`. It returns `true` if the provided code matches the expected value and `false` otherwise. The comparison is performed using a constant-time algorithm to prevent timing attacks.

```kotlin
val isValid: Boolean = generator.isValid(code, ...)
```

--------------------------------

### Migrate from String Secret Creation to ByteArray

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/_autodocs/configuration.md

Shows how to migrate from the deprecated `createRandomSecret()` method to the `createRandomSecretAsByteArray()` method for generating random secrets as ByteArrays.

```kotlin
// Old
val secret: String = GoogleAuthenticator.createRandomSecret()

// New
val secret: ByteArray = GoogleAuthenticator.createRandomSecretAsByteArray()
```

--------------------------------

### Build OTP Auth URI for HOTP

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/_autodocs/api-reference/HmacOneTimePasswordGenerator.md

Creates an OTP Auth URI builder for generating QR codes with HOTP configuration. Preconfigures the builder with the secret, initial counter, algorithm, and digit count.

```kotlin
val config = HmacOneTimePasswordConfig(6, HmacAlgorithm.SHA1)
val generator = HmacOneTimePasswordGenerator("Secret".toByteArray(), config)

val uri = generator.otpAuthUriBuilder(0)
    .label("alice@example.com", "ACME Corp")
    .issuer("ACME Corp")
    .buildToString()

// Returns: otpauth://hotp/ACME%20Corp:alice%40example.com?secret=...&counter=0&algorithm=SHA1&digits=6&issuer=ACME%20Corp
```

--------------------------------

### Configure OTP URL Parameters with UTF-8

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/_autodocs/configuration.md

Sets up an OTP URI builder using UTF-8 encoding for URL parameters, ensuring proper encoding of special characters in labels and issuers.

```kotlin
val builder = OtpAuthUriBuilder.forTotp(base32Secret)
    .label("user@example.com")  // @ becomes %40
    .issuer("Café")  // é encoded properly in UTF-8
```

--------------------------------

### Instantiate GoogleAuthenticator with Base32 Secret

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/_autodocs/api-reference/GoogleAuthenticator.md

Create an instance of GoogleAuthenticator using a Base32-encoded secret as a ByteArray. This is the recommended way to initialize the authenticator.

```kotlin
val google = GoogleAuthenticator("JBSWY3DPEBLW64TMMQ======'".toByteArray())
```

--------------------------------

### Perform Release Checks

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/docs/release.md

Run this task before creating a release pull request to verify the version, README, and CHANGELOG, and to assemble release artifacts.

```shell
task release:check VERSION=<version>
```

--------------------------------

### Format Private Key for gradle.properties

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/docs/release.md

Convert the exported private key into a single line format suitable for the `gradle.properties` file, escaping line breaks.

```shell
gpg --armor --export-secret-keys <key-id> | awk '{printf "%s\n", $0}'
```

--------------------------------

### General OTP Configuration Error Handling

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/_autodocs/errors.md

Shows the standard pattern for catching IllegalArgumentExceptions related to invalid configuration when creating OTP generators.

```kotlin
try {
    // Create generator or build URI
    val config = HmacOneTimePasswordConfig(codeDigits, hmacAlgorithm)
    val generator = HmacOneTimePasswordGenerator(secret, config)
} catch (e: IllegalArgumentException) {
    // Handle configuration error
    println("Invalid configuration: ${e.message}")
    // Present user-friendly error message
    // Provide suggestions for valid values
}
```

--------------------------------

### Handle Negative Initial Counter in Kotlin

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/_autodocs/errors.md

Shows how to catch IllegalArgumentExceptions when providing a negative initial counter for HOTP. Ensure the counter is non-negative.

```kotlin
try {
    OtpAuthUriBuilder.forHotp(-1, base32Secret)
} catch (e: IllegalArgumentException) {
    println(e.message)  // Counter must not be negative.
}

val builder = OtpAuthUriBuilder.forHotp(0, base32Secret)
try {
    builder.counter(-5)
} catch (e: IllegalArgumentException) {
    println(e.message)  // Counter must not be negative.
}
```

```kotlin
val counter = userInput
if (counter < 0) {
    println("Counter must be non-negative")
} else {
    val builder = OtpAuthUriBuilder.forHotp(counter, base32Secret)
}
```

--------------------------------

### Sonatype Publishing Credentials

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/docs/release.md

Configure your local Gradle settings with Sonatype username and password (or user token name and password) for publishing to Maven Central.

```properties
sonatypeUsername=<central-portal-or-ossrh-user-token-name>
sonatypePassword=<central-portal-or-ossrh-user-token-password>
```

--------------------------------

### Handle Zero Time Step for Time-Based OTP Config

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/_autodocs/errors.md

Illustrates how to handle IllegalArgumentException when a zero time step is used without explicitly allowing insecure configurations in TimeBasedOneTimePasswordConfig. This is important for preventing the use of static counters unless intended.

```kotlin
try {
    // Zero time step creates static counter (not recommended)
    TimeBasedOneTimePasswordConfig(0, TimeUnit.SECONDS, 6, HmacAlgorithm.SHA1)
} catch (e: IllegalArgumentException) {
    println(e.message)
    // Time step must be greater than zero. Set allowInsecureConfiguration=true to use a static counter.
}

// Correct: explicitly allow zero time step for legacy
val config = TimeBasedOneTimePasswordConfig(
    0, TimeUnit.SECONDS, 6, HmacAlgorithm.SHA1,
    allowInsecureConfiguration = true
)
```

```kotlin
val config = try {
    TimeBasedOneTimePasswordConfig(timeStep, TimeUnit.SECONDS, 6, HmacAlgorithm.SHA1)
} catch (e: IllegalArgumentException) {
    if (timeStep == 0L) {
        // Legacy configuration requires explicit allowance
        TimeBasedOneTimePasswordConfig(timeStep, TimeUnit.SECONDS, 6, HmacAlgorithm.SHA1, allowInsecureConfiguration = true)
    } else {
        throw e
    }
}
```

--------------------------------

### Google Authenticator Compatible Configuration

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/_autodocs/api-reference/TimeBasedOneTimePasswordConfig.md

Use this snippet to create a configuration compatible with Google Authenticator, using a 30-second time step and SHA1 HMAC algorithm.

```kotlin
import dev.turingcomplete.kotlinonetimepassword.TimeBasedOneTimePasswordConfig
import dev.turingcomplete.kotlinonetimepassword.HmacAlgorithm
import java.util.concurrent.TimeUnit

val config = TimeBasedOneTimePasswordConfig(
    timeStep = 30,
    timeStepUnit = TimeUnit.SECONDS,
    codeDigits = 6,
    hmacAlgorithm = HmacAlgorithm.SHA1
)
```

--------------------------------

### Generate Provisioning QR Code for Google Authenticator

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/_autodocs/README.md

Generates a provisioning URI for Google Authenticator, which can be encoded into a QR code. This is useful for setting up new accounts in authenticator apps.

```kotlin
import dev.turingcomplete.kotlinonetimepassword.GoogleAuthenticator

// Generate new secret
val base32Secret = GoogleAuthenticator.createRandomSecretAsByteArray()

// Create provisioning URI
val google = GoogleAuthenticator(base32Secret)
val qrUri = google.otpAuthUriBuilder()
    .label("user@example.com", "My Service")
    .issuer("My Service")
    .buildToString()

// Encode qrUri as QR code and scan with authenticator app
```

--------------------------------

### Millisecond Precision TOTP Configuration

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/_autodocs/configuration.md

This configuration demonstrates using milliseconds for the time step, allowing for finer-grained time-based OTP generation.

```kotlin
val config = TimeBasedOneTimePasswordConfig(
    timeStep = 500,
    timeStepUnit = TimeUnit.MILLISECONDS,
    codeDigits = 6,
    hmacAlgorithm = HmacAlgorithm.SHA1
)
```

--------------------------------

### OtpAuthUriBuilder Constructor

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/_autodocs/api-reference/OtpAuthUriBuilder.md

Initializes the OtpAuthUriBuilder with the OTP type, Base32 secret, and optional padding removal and charset.

```APIDOC
## OtpAuthUriBuilder Constructor

### Description
Initializes the OtpAuthUriBuilder with the OTP type, Base32 secret, and optional padding removal and charset.

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- None

### Parameters
- **type** (String) - Required - OTP Auth URI type, usually "totp" or "hotp".
- **base32Secret** (ByteArray) - Required - Shared secret as Base32-encoded bytes. Must be valid Base32.
- **removePaddingFromBase32Secret** (Boolean) - Optional - Default: `true` - Remove Base32 padding characters (`=`) from the secret URI parameter. Key URI Format expects unpadded Base32.
- **charset** (Charset) - Optional - Default: UTF-8 - Character set for URL encoding.

### Throws
- `IllegalArgumentException` if `base32Secret` is not a valid non-empty Base32 value.

### Validation
Base32 secret must match regex `^[A-Z2-7]+={0,6}$` (uppercase letters A-Z, digits 2-7, and 0–6 padding characters).
```

--------------------------------

### Recommended Secure HOTP Configuration

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/_autodocs/configuration.md

Use this configuration for standard HOTP generation. It sets the code digits to 6 and uses the SHA1 HMAC algorithm.

```kotlin
val config = HmacOneTimePasswordConfig(6, HmacAlgorithm.SHA1)
```

--------------------------------

### otpAuthUriBuilder

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/_autodocs/api-reference/HmacOneTimePasswordGenerator.md

Creates an OTP Auth URI builder for generating QR codes with HOTP configuration. Preconfigures the builder with the secret, counter, algorithm, and digit count.

```APIDOC
## otpAuthUriBuilder

### Description
Creates an OTP Auth URI builder for generating QR codes with HOTP configuration. Preconfigures the builder with the secret, counter, algorithm, and digit count.

### Method
N/A (Method)

### Endpoint
N/A (Method)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Parameters
- **initialCounter** (Long) - Required - The initial counter value to place in the URI.

### Request Example
```kotlin
val uri = generator.otpAuthUriBuilder(0)
    .label("alice@example.com", "ACME Corp")
    .issuer("ACME Corp")
    .buildToString()

// Returns: otpauth://hotp/ACME%20Corp:alice%40example.com?secret=...&counter=0&algorithm=SHA1&digits=6&issuer=ACME%20Corp
```

### Response
#### Success Response
- **return value** (OtpAuthUriBuilder.Hotp) - An `OtpAuthUriBuilder.Hotp` preconfigured with the Base32-encoded secret, initial counter, algorithm, and digit count.

### Response Example
```
OtpAuthUriBuilder.Hotp
```
```

--------------------------------

### HmacOneTimePasswordConfig Convenience Constructor

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/_autodocs/api-reference/HmacOneTimePasswordConfig.md

A convenience constructor for HmacOneTimePasswordConfig that defaults `allowInsecureConfiguration` to `false`. Useful for standard HOTP configurations.

```APIDOC
## HmacOneTimePasswordConfig(codeDigits: Int, hmacAlgorithm: HmacAlgorithm)

### Description
Creates a configuration for HMAC-based one-time password generation using the default security settings. This constructor internally calls the primary constructor with `allowInsecureConfiguration` set to `false`.

### Parameters
#### Parameters
- **codeDigits** (Int) - Required - Number of digits in the generated code.
- **hmacAlgorithm** (HmacAlgorithm) - Required - HMAC algorithm used to generate codes.

### Behavior
Internally calls the primary constructor with `allowInsecureConfiguration = false`.
```

--------------------------------

### Verify Public Key Retrieval

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/docs/release.md

Verify that your public GPG key can be successfully retrieved from the specified keyserver.

```shell
gpg --keyserver keyserver.ubuntu.com --recv-keys <key-id>
```

--------------------------------

### Build OTP Auth URI as String

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/_autodocs/api-reference/OtpAuthUriBuilder.md

Builds the complete OTP authentication URI as a String. Warning: The returned string contains the shared secret. Consider using buildToByteArray() for security-sensitive applications.

```kotlin
val uri = builder
    .label("user@example.com", "Service")
    .issuer("Service")
    .digits(6)
    .buildToString()

println(uri)
// otpauth://totp/Service:user%40example.com?digits=6&secret=JBSWY3DPEBLW64TMMQ&issuer=Service
```

--------------------------------

### Legacy Static Counter TOTP Configuration

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/_autodocs/configuration.md

This configuration is for legacy testing purposes, using a time step of 0 to simulate a static counter. It requires `allowInsecureConfiguration` to be set to true.

```kotlin
val config = TimeBasedOneTimePasswordConfig(
    timeStep = 0,
    timeStepUnit = TimeUnit.SECONDS,
    codeDigits = 6,
    hmacAlgorithm = HmacAlgorithm.SHA1,
    allowInsecureConfiguration = true
)
```

--------------------------------

### Publish to Sonatype Repository

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/docs/release.md

After the release pull request is merged, use this command to publish the artifacts to the Sonatype repository with signing enabled.

```shell
./gradlew publishMavenJavaPublicationToSonatypeRepository -Psigning.required=true
```

--------------------------------

### Update README with Version

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/docs/release.md

Use this task to update the README file with the correct version information and Maven coordinates before creating a release pull request.

```shell
task release:update-readme VERSION=<version>
```

--------------------------------

### Build OTPAuth URI with GoogleAuthenticator Configuration

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/README.md

Generates an OTPAuth URI string using the configuration from a GoogleAuthenticator instance. The generated URI includes default parameters like algorithm, digits, and period.

```kotlin
GoogleAuthenticator(Base32().encode("secret".toByteArray()))
  .otpAuthUriBuilder()
  .issuer("Company")
  .buildToString()
```

--------------------------------

### label Method

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/_autodocs/api-reference/OtpAuthUriBuilder.md

Sets the label path part of the URI, which includes the account name and optionally the issuer.

```APIDOC
## label

### Description
Sets the label path part of the URI (the part before the `?`). This includes the account name and optionally the issuer.

### Method
Instance method

### Endpoint
N/A (Instance method)

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- None

### Parameters
- **accountName** (String) - Required - The account name shown by authenticator apps. URL-encoded.
- **issuer** (String?) - Optional - Optional provider/service name. URL-encoded. If provided, appears as `issuer:accountName`.
- **encodeSeparator** (Boolean) - Optional - Default: `false` - When `true`, the colon between issuer and account name is URL-encoded as `%3A`.

### Returns
This builder for method chaining.

### Throws
- `IllegalArgumentException` if account name or issuer contains a literal or URL-encoded colon.

### Example
```kotlin
val builder = OtpAuthUriBuilder.forTotp(secret)
    .label("alice@example.com", "Example Corp")
```

### URI Result Example
```
otpauth://totp/Example%20Corp:alice%40example.com?...
```
```

--------------------------------

### Build OTPAuth URI for QR Code

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/_autodocs/api-reference/TimeBasedOneTimePasswordGenerator.md

Creates an OTPAuth URI builder to generate QR codes for TOTP configuration. This builder is preconfigured with the secret, algorithm, digits, and time step from the generator's configuration.

```kotlin
val config = TimeBasedOneTimePasswordConfig(30, TimeUnit.SECONDS, 6, HmacAlgorithm.SHA1)
val generator = TimeBasedOneTimePasswordGenerator("Secret".toByteArray(), config)

val uri = generator.otpAuthUriBuilder()
    .label("user@example.com", "My Service")
    .issuer("My Service")
    .buildToString()
```

--------------------------------

### Derive Version from Changelog

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/docs/release.md

The project version is dynamically determined by the Spotless Changelog plugin, reading from the CHANGELOG.md file. Ensure your release version is correctly formatted in the changelog.

```kotlin
version = spotlessChangelog.versionNext
```

--------------------------------

### HmacOneTimePasswordConfig Convenience Constructor

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/_autodocs/api-reference/HmacOneTimePasswordConfig.md

Provides a convenience constructor for HmacOneTimePasswordConfig that defaults allowInsecureConfiguration to false.

```kotlin
HmacOneTimePasswordConfig(
    codeDigits: Int,
    hmacAlgorithm: HmacAlgorithm
)
```

--------------------------------

### Legacy HOTP Configuration

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/_autodocs/configuration.md

This configuration is for legacy systems or specific test vectors. It allows insecure settings like fewer than 6 code digits and explicitly sets the HMAC algorithm to SHA1.

```kotlin
val config = HmacOneTimePasswordConfig(
    codeDigits = 4,
    hmacAlgorithm = HmacAlgorithm.SHA1,
    allowInsecureConfiguration = true
)
```

--------------------------------

### OtpAuthUriBuilder.Hotp Constructor

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/_autodocs/api-reference/OtpAuthUriBuilder.md

Constructor for creating a builder specifically for Hash-based One-Time Password (HOTP) URIs, requiring an initial counter value.

```APIDOC
## OtpAuthUriBuilder.Hotp Constructor

### Description
Subclass for building HOTP URIs.

### Method
```kotlin
class Hotp(initialCounter: Long, base32Secret: ByteArray) : OtpAuthUriBuilder<Hotp>("hotp", base32Secret)
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **initialCounter** (Long) - Required - Initial counter value. Constructor automatically sets the `counter` parameter to `initialCounter`.
- **base32Secret** (ByteArray) - Required - Base32-encoded secret.
```

--------------------------------

### Create HOTP Builder

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/_autodocs/api-reference/OtpAuthUriBuilder.md

Use this factory method to create a builder for a Hash-based One-Time Password (HOTP) URI. Requires an initial counter value and a Base32-encoded secret.

```kotlin
val secret = Base32().encode("MySecret".toByteArray())
val builder = OtpAuthUriBuilder.forHotp(0, secret)
```

--------------------------------

### Initialize TOTP Generator

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/README.md

Instantiate the TimeBasedOneTimePasswordGenerator with a secret and configuration. The configuration includes code digits, HMAC algorithm, and time step.

```kotlin
val secret = "Leia"
val config = TimeBasedOneTimePasswordConfig(codeDigits = 8, 
                                            hmacAlgorithm = HmacAlgorithm.SHA1,
                                            timeStep = 30, 
                                            timeStepUnit = TimeUnit.SECONDS)
val timeBasedOneTimePasswordGenerator = TimeBasedOneTimePasswordGenerator(secret.toByteArray(), config)
```

--------------------------------

### Constructor

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/_autodocs/api-reference/TimeBasedOneTimePasswordGenerator.md

Initializes a new instance of the TimeBasedOneTimePasswordGenerator. The shared secret is copied during construction.

```APIDOC
## Constructor

### Description
Initializes a new instance of the TimeBasedOneTimePasswordGenerator with a shared secret and configuration.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **secret** (ByteArray) - Required - The shared secret (copied during construction). Must not be empty.
- **config** (TimeBasedOneTimePasswordConfig) - Required - Configuration including time step, HMAC algorithm, and code digit count.

### Throws
`IllegalArgumentException` if `secret` is empty.
```

--------------------------------

### Build OTP Auth URI for Google Authenticator

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/_autodocs/api-reference/GoogleAuthenticator.md

Construct an OTP Auth URI pre-configured for Google Authenticator's settings (SHA1, 6 digits, 30-second period). Use the `label` and `issuer` methods to customize the URI.

```kotlin
val uri = google.otpAuthUriBuilder()
    .label("alice@example.com", "Example Corp")
    .issuer("Example Corp")
    .buildToString()
```

--------------------------------

### Export Private Key for Gradle

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/docs/release.md

Export the private GPG key in armor format. This key will be used for in-memory signing by Gradle.

```shell
gpg --armor --export-secret-keys <key-id>
```

--------------------------------

### Verify Computed Gradle Version

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/docs/release.md

Before proceeding with a release, verify that the Gradle version computed by the build matches the intended release version.

```shell
./gradlew -q printVersion
```

--------------------------------

### Handle Negative Time Step for Time-Based OTP Config

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/_autodocs/errors.md

Demonstrates catching IllegalArgumentException when the time step is negative during TimeBasedOneTimePasswordConfig initialization. This is relevant for ensuring valid time intervals for OTP generation.

```kotlin
try {
    TimeBasedOneTimePasswordConfig(-30, TimeUnit.SECONDS, 6, HmacAlgorithm.SHA1)
} catch (e: IllegalArgumentException) {
    println(e.message)
}
```

```kotlin
val timeStep = userInput
if (timeStep < 0) {
    println("Time step must be non-negative")
} else {
    val config = TimeBasedOneTimePasswordConfig(timeStep, TimeUnit.SECONDS, 6, HmacAlgorithm.SHA1)
}
```

--------------------------------

### Generate New GPG Key Pair

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/docs/release.md

Use this command to generate a new GPG key pair. Ensure you select an RSA key and set a strong passphrase.

```shell
gpg --full-generate-key
```

--------------------------------

### otpAuthUriBuilder

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/_autodocs/api-reference/TimeBasedOneTimePasswordGenerator.md

Creates an OTP Auth URI builder for generating QR codes with TOTP configuration. This is useful for integrating with authenticator apps.

```APIDOC
## otpAuthUriBuilder

### Description
Creates an OTP Auth URI builder for generating QR codes with TOTP configuration. The builder is preconfigured with the secret, algorithm, digits, and time step from the generator's configuration.

### Method
```kotlin
fun otpAuthUriBuilder(): OtpAuthUriBuilder.Totp
```

### Parameters
None.

### Returns
An `OtpAuthUriBuilder.Totp` instance ready for further configuration (label, issuer) and building the URI string.

### Example
```kotlin
val config = TimeBasedOneTimePasswordConfig(30, TimeUnit.SECONDS, 6, HmacAlgorithm.SHA1)
val generator = TimeBasedOneTimePasswordGenerator("Secret".toByteArray(), config)

val uri = generator.otpAuthUriBuilder()
    .label("user@example.com", "My Service")
    .issuer("My Service")
    .buildToString()
```
```

--------------------------------

### TimeBasedOneTimePasswordConfig Convenience Constructor

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/_autodocs/api-reference/TimeBasedOneTimePasswordConfig.md

A convenience constructor for Time-Based One-Time Password (TOTP) configuration that defaults `allowInsecureConfiguration` to `false`.

```APIDOC
## TimeBasedOneTimePasswordConfig Convenience Constructor

### Description
A convenience constructor for Time-Based One-Time Password (TOTP) configuration that defaults `allowInsecureConfiguration` to `false`.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **timeStep** (Long) - Required - Size of one TOTP time step.
- **timeStepUnit** (TimeUnit) - Required - Unit for `timeStep`.
- **codeDigits** (Int) - Required - Number of digits in generated codes.
- **hmacAlgorithm** (HmacAlgorithm) - Required - HMAC algorithm.
```

--------------------------------

### Build OTP Auth URI as ByteArray

Source: https://github.com/marcelkliemannel/kotlin-onetimepassword/blob/main/_autodocs/api-reference/OtpAuthUriBuilder.md

Builds the OTP authentication URI as a ByteArray, avoiding the creation of a URI string that contains the secret. This is recommended for security-sensitive applications.

```kotlin
val uriBytes = builder
    .label("user@example.com", "Service")
    .issuer("Service")
    .buildToByteArray()

// URI is now only in memory as bytes, not an immutable String
```