### Generate HOTP Code - Lua

Source: https://context7.com/tilkinsc/luaotp/llms.txt

This code demonstrates how to generate a HMAC-based One-Time Password (HOTP) code. It uses the 'hotp' and 'otp' modules. The 'HOTP.at' function generates a code based on a given counter value. Unlike TOTP, HOTP codes are not time-dependent but rely on a synchronized counter. This example shows generating codes for sequential counter values.

```lua
local HOTP = require("hotp")
local OTP = require("otp")

OTP.type = "hotp"
local instance = OTP.new("JBSWY3DPEHPK3PXP", 6, "sha1")

-- Generate HOTP code for counter value 1
local code = HOTP.at(instance, 1)
print("HOTP at counter 1: " .. code)  -- Output: "996554"

-- Generate for subsequent counter values
for counter = 1, 5 do
    local hotp_code = HOTP.at(instance, counter)
    print("Counter " .. counter .. ": " .. hotp_code)
end
```

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

### Create OTP Instance

Source: https://context7.com/tilkinsc/luaotp/llms.txt

Initializes a new OTP instance, specifying the mode (TOTP or HOTP), secret key, desired code length, digest algorithm, and mode-specific parameters.

```APIDOC
## Create OTP Instance

### Description
Creates a new OTP instance configured for either TOTP or HOTP mode. The instance stores the secret key, number of digits, digest algorithm, and mode-specific parameters like the time interval for TOTP.

### Method
Requires initialization of the `OTP` module and setting `OTP.type` to either `"totp"` or `"hotp"`.

### Endpoint
N/A (Library function)

### Parameters
#### Global OTP Parameters (set before `OTP.new`)
- **OTP.type** (string) - Required - The type of OTP to create, either `"totp"` or `"hotp"`.

#### `OTP.new` Parameters
- **secret** (string) - Required - The base32 encoded secret key.
- **digits** (number) - Required - The desired length of the OTP code (e.g., 6).
- **digest** (string) - Required - The HMAC digest algorithm (e.g., `"sha1"`).
- **interval** (number) - Optional (TOTP only) - The time interval in seconds for TOTP codes (defaults to 30).

### Request Example
```lua
local OTP = require("otp")

-- Create TOTP instance
OTP.type = "totp"
local totp_instance = OTP.new("JBSWY3DPEHPK3PXP", 6, "sha1", 30)

-- Create HOTP instance
OTP.type = "hotp"
local hotp_instance = OTP.new("JBSWY3DPEHPK3PXP", 6, "sha1")
```

### Response
#### Success Response (Instance Object)
- **instance** (object) - The configured OTP instance.

#### Response Example
(Instance object is internal and not directly represented as a JSON response in this library context.)
```

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

### Create OTP Instance (TOTP/HOTP) - Lua

Source: https://context7.com/tilkinsc/luaotp/llms.txt

This snippet demonstrates how to create a new OTP instance, specifying whether it's for Time-based (TOTP) or Counter-based (HOTP) authentication. It shows the parameters required, including the secret key, number of digits, digest algorithm, and mode-specific settings like the time interval for TOTP. Dependencies include 'otp', 'totp', and 'hotp' modules.

```lua
local OTP = require("otp")
local TOTP = require("totp")
local HOTP = require("hotp")

-- Create TOTP instance (time-based)
OTP.type = "totp"
local totp_instance = OTP.new("JBSWY3DPEHPK3PXP", 6, "sha1", 30)
-- Parameters: secret (base32), digits (6), digest (sha1), interval (30 seconds)

-- Create HOTP instance (counter-based)
OTP.type = "hotp"
local hotp_instance = OTP.new("JBSWY3DPEHPK3PXP", 6, "sha1")
-- Parameters: secret (base32), digits (6), digest (sha1)
```

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

### Verify TOTP Code

Source: https://context7.com/tilkinsc/luaotp/llms.txt

Validates a provided TOTP code against the expected value, allowing for a configurable tolerance in time windows to account for clock skew.

```APIDOC
## Verify TOTP Code

### Description
Validates a TOTP code against the expected value. It can check against the current time window or a range of adjacent time windows to accommodate clock synchronization differences.

### Method
`TOTP.verify(instance, code, time, tolerance)`

### Endpoint
N/A (Library function)

### Parameters
#### Function Parameters
- **instance** (object) - Required - The TOTP instance created with `OTP.new`.
- **code** (string) - Required - The TOTP code provided by the user to verify.
- **time** (number) - Required - The Unix timestamp against which to verify the code.
- **tolerance** (number) - Optional - The number of time windows to check forwards and backwards from the `time`. A value of `0` checks only the exact window. Defaults to `0`.

### Request Example
```lua
local TOTP = require("totp")
local OTP = require("otp")

OTP.type = "totp"
local instance = OTP.new("JBSWY3DPEHPK3PXP", 6, "sha1", 30)

-- Verify code at current time (exact match only)
local user_code = "123456"
local is_valid = TOTP.verify(instance, user_code, os.time(), 0)
print("Code valid: " .. tostring(is_valid))

-- Verify with 4-window tolerance
local historical_code = TOTP.at(instance, 0, 0) -- Assume this is the code at time 0
local is_valid_window = TOTP.verify(instance, historical_code, 0, 4)
print("Code valid in window: " .. tostring(is_valid_window))

-- Example of an invalid code attempt
local invalid_code = "000000"
local is_invalid = TOTP.verify(instance, invalid_code, os.time(), 1)
print("Invalid code check: " .. tostring(is_invalid))
```

### Response
#### Success Response (200)
- **isValid** (boolean) - `true` if the provided code is valid within the specified time and tolerance, `false` otherwise.

#### Response Example
```
Code valid: true
Code valid in window: true
Invalid code check: false
```
```

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

### Array and String Utilities in Lua

Source: https://context7.com/tilkinsc/luaotp/llms.txt

Provides essential helper functions for manipulating byte arrays and converting between strings and byte arrays. These utilities are foundational for various OTP operations, including reversing byte sequences and character encoding/decoding.

```lua
local UTIL = require("util")

-- Reverse an array
local original = {1, 2, 3, 4, 5}
local reversed = UTIL.arr_reverse(original)
-- reversed = {5, 4, 3, 2, 1}

-- Convert byte array to string
local bytes = {72, 101, 108, 108, 111}
local str = UTIL.byte_arr_tostring(bytes)
print(str)  -- Output: "Hello"

-- Convert string to byte array
local text = "Hello"
local byte_array = UTIL.str_to_byte(text)
-- byte_array = {72, 101, 108, 108, 111}

-- Chain conversions
local data = "Test"
local as_bytes = UTIL.str_to_byte(data)
local reversed_bytes = UTIL.arr_reverse(as_bytes)
local result = UTIL.byte_arr_tostring(reversed_bytes)
print(result)  -- Output: "tseT"
```

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

### Verify TOTP Code - Lua

Source: https://context7.com/tilkinsc/luaotp/llms.txt

This snippet shows how to verify a Time-based One-Time Password (TOTP) code. It uses the 'totp' and 'otp' modules. The 'TOTP.verify' function checks a provided code against the expected value for a given timestamp, with an option to specify a tolerance window to account for clock synchronization issues between the client and server. It returns true if the code is valid within the specified parameters, and false otherwise.

```lua
local TOTP = require("totp")
local OTP = require("otp")

OTP.type = "totp"
local instance = OTP.new("JBSWY3DPEHPK3PXP", 6, "sha1", 30)

-- Verify code at current time (exact match only)
local user_code = "123456"
local is_valid = TOTP.verify(instance, user_code, os.time(), 0)
print("Code valid: " .. tostring(is_valid))  -- true or false

-- Verify with 4-window tolerance (checks ±4 time windows)
local is_valid_window = TOTP.verify(instance, 282760, 0, 4)
print("Code valid in window: " .. tostring(is_valid_window))  -- true

-- Verify historical code (will fail if outside window)
local old_code = TOTP.verify(instance, 576203, os.time(), 4)
print("Old code valid: " .. tostring(old_code))  -- false
```

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

### Generate TOTP Code (Specific Time)

Source: https://context7.com/tilkinsc/luaotp/llms.txt

Generates a TOTP code for a specific timestamp, allowing access to codes from adjacent time windows using an offset.

```APIDOC
## Generate TOTP Code (Specific Time)

### Description
Generates a TOTP code for a specific timestamp with an optional counter offset. This allows for generating codes for past or future time windows relative to the provided timestamp.

### Method
`TOTP.at(instance, time, offset)`

### Endpoint
N/A (Library function)

### Parameters
#### Function Parameters
- **instance** (object) - Required - The TOTP instance created with `OTP.new`.
- **time** (number) - Required - The Unix timestamp for which to generate the code.
- **offset** (number) - Optional - An integer representing the offset from the `time` parameter's time window. `0` is the window containing `time`, `1` is the next window, `-1` is the previous window, etc. Defaults to `0`.

### Request Example
```lua
local TOTP = require("totp")
local OTP = require("otp")

OTP.type = "totp"
local instance = OTP.new("JBSWY3DPEHPK3PXP", 6, "sha1", 30)

-- Generate code at timeblock 0 (Unix epoch)
local code_at_zero = TOTP.at(instance, 0, 0)
print("TOTP at time 0: " .. code_at_zero)

-- Generate code at specific time with offset for the next window
local current_time = os.time()
local code_next_window = TOTP.at(instance, current_time, 1)
print("Code in next window: " .. code_next_window)

-- Generate code for the previous window
local code_prev_window = TOTP.at(instance, current_time, -1)
print("Code in previous window: " .. code_prev_window)
```

### Response
#### Success Response (200)
- **code** (string) - The generated TOTP code for the specified time and offset.

#### Response Example
```
TOTP at time 0: 282760
Code in next window: 123456
Code in previous window: 987654
```
```

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

### Verify HOTP Code with Lua

Source: https://context7.com/tilkinsc/luaotp/llms.txt

Validates a given HOTP code against a specific counter value using a pre-configured OTP instance. It returns true if the code is valid, and false otherwise. This function is crucial for user authentication flows.

```lua
local HOTP = require("hotp")
local OTP = require("otp")

OTP.type = "hotp"
local instance = OTP.new("JBSWY3DPEHPK3PXP", 6, "sha1")

-- Verify HOTP code
local user_code = "996554"
local counter = 1
local is_valid = HOTP.verify(instance, user_code, counter)
print("HOTP verification result: " .. tostring(is_valid))  -- true

-- Invalid code example
local invalid = HOTP.verify(instance, "000000", counter)
print("Invalid code result: " .. tostring(invalid))  -- false
```

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

### Generate TOTP Code (Current/Specific Time) - Lua

Source: https://context7.com/tilkinsc/luaotp/llms.txt

This code illustrates how to generate a Time-based One-Time Password (TOTP) code using the current system time or a specific timestamp. It utilizes the 'totp' and 'otp' modules. The function 'TOTP.now' generates a code for the present moment, while 'TOTP.at' allows generation for a specific time, with optional counter offsets to check adjacent time windows.

```lua
local TOTP = require("totp")
local OTP = require("otp")

OTP.type = "totp"
local instance = OTP.new("JBSWY3DPEHPK3PXP", 6, "sha1", 30)

-- Generate code for current time
local code = TOTP.now(instance)
print("Current TOTP code: " .. code)  -- Output: "123456" (example)

-- Generate code with custom time override
local custom_time = os.time()
local code_at_time = TOTP.now(instance, custom_time)
print("TOTP at specific time: " .. code_at_time)

-- Generate code at timeblock 0 (Unix epoch)
local code_at_zero = TOTP.at(instance, 0, 0)
print("TOTP at time 0: " .. code_at_zero)  -- Output: "282760"

-- Generate code at specific time with offset
local current_time = os.time()
local code_next_window = TOTP.at(instance, current_time, 1)  -- Next time window
local code_prev_window = TOTP.at(instance, current_time, -1) -- Previous time window
print("Code in next window: " .. code_next_window)
print("Code in previous window: " .. code_prev_window)
```

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

### Generate Random Base32 Secret Key in Lua

Source: https://context7.com/tilkinsc/luaotp/llms.txt

Creates a random Base32-encoded secret key suitable for OTP authentication. It utilizes a secure random number generator and a custom alphabet to avoid confusing characters. The generated secret can then be used to initialize OTP instances.

```lua
local UTIL = require("util")

-- Seed the random number generator
math.randomseed(os.time())
math.random(); math.random()  -- Warm up RNG

-- Generate 16-character base32 secret
local secret = UTIL.random_base32(16, UTIL.default_chars)
print("Generated secret: " .. secret)
-- Output: "KBZGC3DQNFXSA4TP" (example)

-- Generate custom length secret
local long_secret = UTIL.random_base32(32)
print("Long secret: " .. long_secret)

-- Use generated secret in OTP instance
local OTP = require("otp")
OTP.type = "totp"
local new_instance = OTP.new(secret, 6, "sha1", 30)
```

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

### Generate HOTP Code

Source: https://context7.com/tilkinsc/luaotp/llms.txt

Generates a Hash-based Message Authentication Code (HMAC)-based One-Time Password (HOTP) code based on a specific counter value.

```APIDOC
## Generate HOTP Code

### Description
Generates a counter-based OTP code for a specific counter value. Unlike TOTP, HOTP codes do not inherently expire based on time but must be synchronized between the client and server using the counter.

### Method
`HOTP.at(instance, counter)`

### Endpoint
N/A (Library function)

### Parameters
#### Function Parameters
- **instance** (object) - Required - The HOTP instance created with `OTP.new`.
- **counter** (number) - Required - The current counter value used for generating the code.

### Request Example
```lua
local HOTP = require("hotp")
local OTP = require("otp")

OTP.type = "hotp"
local instance = OTP.new("JBSWY3DPEHPK3PXP", 6, "sha1")

-- Generate HOTP code for counter value 1
local code_1 = HOTP.at(instance, 1)
print("HOTP at counter 1: " .. code_1)

-- Generate for subsequent counter values
for counter_val = 2, 5 do
    local hotp_code = HOTP.at(instance, counter_val)
    print("Counter " .. counter_val .. ": " .. hotp_code)
end
```

### Response
#### Success Response (200)
- **code** (string) - The generated HOTP code for the specified counter.

#### Response Example
```
HOTP at counter 1: 996554
Counter 2: 123456
Counter 3: 789012
Counter 4: 112233
Counter 5: 445566
```
```

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

### Convert Integer to Byte String in Lua

Source: https://context7.com/tilkinsc/luaotp/llms.txt

Converts an integer into a byte string representation, with optional padding to a specified length. This is critical for the HMAC operations involved in OTP code generation, ensuring consistent input formats.

```lua
local OTP = require("otp")

-- Convert counter to 8-byte string
local byte_string = OTP.int_to_bytestring(1, 8)
-- Returns: "\0\0\0\0\0\0\0\1"

-- Custom padding
local padded = OTP.int_to_bytestring(255, 4)
-- Returns: "\0\0\0\xFF"

-- Used internally in OTP generation
local counter = 12345
local input_bytes = OTP.int_to_bytestring(counter)
```

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

### Generate TOTP Code (Current Time)

Source: https://context7.com/tilkinsc/luaotp/llms.txt

Generates a Time-based One-Time Password (TOTP) code based on the current system time. The code is typically valid for a defined time interval.

```APIDOC
## Generate TOTP Code (Current Time)

### Description
Generates a time-based OTP code using the current system time. Returns a code of the specified length (defaulting to 6 digits) that changes at the defined interval (defaulting to 30 seconds).

### Method
`TOTP.now(instance, time)`

### Endpoint
N/A (Library function)

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

#### Query Parameters
N/A

#### Request Body
N/A

#### Function Parameters
- **instance** (object) - Required - The TOTP instance created with `OTP.new`.
- **time** (number) - Optional - A specific Unix timestamp to generate the code for. If omitted, the current system time (`os.time()`) is used.

### Request Example
```lua
local TOTP = require("totp")
local OTP = require("otp")

OTP.type = "totp"
local instance = OTP.new("JBSWY3DPEHPK3PXP", 6, "sha1", 30)

-- Generate code for current time
local code = TOTP.now(instance)
print("Current TOTP code: " .. code)

-- Generate code with custom time override
local custom_time = os.time() - 60 -- Example: 60 seconds ago
local code_at_time = TOTP.now(instance, custom_time)
print("TOTP at specific time: " .. code_at_time)
```

### Response
#### Success Response (200)
- **code** (string) - The generated TOTP code.

#### Response Example
```
-- Output:
Current TOTP code: 123456
TOTP at specific time: 789012
```
```

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

### URL Encode Strings in Lua

Source: https://context7.com/tilkinsc/luaotp/llms.txt

Encodes strings to be URL-safe, replacing special characters with their percent-encoded equivalents. This utility is essential for constructing valid OTP URIs that can be correctly parsed by authenticator applications.

```lua
local UTIL = require("util")

-- Encode special characters
local encoded = UTIL.encode_url("user@example.com")
print("Encoded: " .. encoded)  -- Output: "user@example.com"

-- Encode spaces and special characters
local complex = UTIL.encode_url("My App Name: Test #1")
print("Encoded complex: " .. complex)
-- Output: "My%20App%20Name:%20Test%20%231"

-- Use in URI building
local label = UTIL.encode_url("My Account")
local issuer = UTIL.encode_url("My Company")
```

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

### Build OTP URIs for TOTP and HOTP in Lua

Source: https://context7.com/tilkinsc/luaotp/llms.txt

Generates otpauth:// URIs for both Time-based One-Time Password (TOTP) and HMAC-based One-Time Password (HOTP). These URIs can be encoded into QR codes for easy integration with authenticator apps. The function accepts various parameters like secret, account name, issuer, algorithm, digits, and period (for TOTP) or counter (for HOTP).

```lua
local OTP = require("otp")
local UTIL = require("util")

-- Build TOTP URI
local totp_uri = UTIL.build_uri(
    "JBSWY3DPEHPK3PXP",           -- secret (base32)
    "user@example.com",            -- account name
    nil,                           -- counter (nil for TOTP)
    "MyApp",                       -- issuer name
    "SHA1",                        -- algorithm
    6,                             -- digits
    30                             -- period (seconds)
)
print("TOTP URI: " .. totp_uri)
-- Output: otpauth://totp/MyApp:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=MyApp&algorithm=SHA1&digits=6&period=30

-- Build HOTP URI
local hotp_uri = UTIL.build_uri(
    "JBSWY3DPEHPK3PXP",           -- secret (base32)
    "user@example.com",            -- account name
    52,                            -- initial counter
    "MyApp",                       -- issuer name
    "SHA1",                        -- algorithm
    6,                             -- digits
    nil                            -- period (nil for HOTP)
)
print("HOTP URI: " .. hotp_uri)
-- Output: otpauth://hotp/MyApp:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=MyApp&counter=52&algorithm=SHA1&digits=6
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.