### Start OTP API Server Locally

Source: https://github.com/ja7ad/otp/blob/main/README.md

Starts the OTP API server on the specified local address and port. This command is used to run the prebuilt binary for local testing or deployment. The server provides endpoints for generating and validating various OTP codes. Ensure the binary is downloaded from the latest release page.

```shell
otp -serve localhost:8080
```

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

### Install OTP Go Package

Source: https://github.com/ja7ad/otp/blob/main/README.md

Installs the latest version of the OTP Go package using the go get command. This is the primary method for integrating the OTP library into Go projects. Ensure you have Go version 1.24 or higher installed.

```bash
go get -u github.com/ja7ad/otp
```

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

### Generate and Validate OCRA using Ja7ad/otp

Source: https://github.com/ja7ad/otp/blob/main/README.md

This Go example illustrates the generation and validation of an OCRA (OATH Computationally<bos>Secure Authentication) code using a specified suite and challenge. It requires the 'github.com/ja7ad/otp' library and demonstrates handling potential errors during the process.

```go
package main

import (
	"fmt"
	"github.com/ja7ad/otp"
)

func main() {
	secret, err := otp.RandomSecret(otp.SHA1)
	if err != nil {
		panic(err)
	}

	suite := otp.MustRawSuite("OCRA-1:HOTP-SHA1-6:QN08")

	code, err := otp.GenerateOCRA(secret, suite, otp.OCRAInput{
		Challenge: []byte("12345678"),
	})

	if err != nil {
		panic(err)
	}

	ok, err := otp.ValidateOCRA(secret, code, suite, otp.OCRAInput{
		Challenge: []byte("12345678"),
	})
	if err != nil {
		panic(err)
	}

	fmt.Println(ok)
}
```

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

### Install otp-js Package

Source: https://github.com/ja7ad/otp/blob/main/otp-js/README.md

Installs the otp-js library using npm. This is the primary method for integrating the library into a Node.js or browser project.

```bash
npm i @ja7ad/otp-js
```

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

### Run OTP API Server with Docker

Source: https://github.com/ja7ad/otp/blob/main/README.md

Launches the OTP API server using a Docker container. This allows for easy deployment and access to the OTP functionalities as a web service. The container exposes port 8080 for API access. Ensure Docker is installed and running.

```bash
docker pull ja7adr/otp
docker run -p 8080:8080 ja7adr/otp
```

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

### Generate HOTP Codes with /ja7ad/otp in Go

Source: https://context7.com/ja7ad/otp/llms.txt

This Go code snippet demonstrates how to generate HMAC-Based One-Time Passwords (HOTP) using the /ja7ad/otp library. It covers generating random secrets, creating HOTP codes with default and custom parameters, and includes an example of output. Ensure the 'github.com/ja7ad/otp' package is imported.

```go
package main

import (
    "fmt"
    "log"
    "github.com/ja7ad/otp"
)

func main() {
    // Generate a secret
    secret, err := otp.RandomSecret(otp.SHA1)
    if err != nil {
        log.Fatal(err)
    }

    // Generate HOTP codes with incrementing counter
    for counter := uint64(1); counter <= 5; counter++ {
        code, err := otp.GenerateHOTP(secret, counter, otp.DefaultHOTPParam)
        if err != nil {
            log.Fatal(err)
        }
        fmt.Printf("Counter %d: %s\n", counter, code)
    }

    // Generate HOTP with custom parameters
    customParam := &otp.Param{
        Digits:    otp.EightDigits,
        Algorithm: otp.SHA512,
        Skew:      2,
    }
    customCode, err := otp.GenerateHOTP(secret, 100, customParam)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Custom HOTP (Counter 100): %s\n", customCode)

    // Output example:
    // Counter 1: 123456
    // Counter 2: 234567
    // Counter 3: 345678
    // Counter 4: 456789
    // Counter 5: 567890
    // Custom HOTP (Counter 100): 12345678
}
```

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

### Validate OCRA Codes with /ja7ad/otp in Go

Source: https://context7.com/ja7ad/otp/llms.txt

This Go code snippet demonstrates how to validate OCRA (Challenge-Response Authentication) codes using the /ja7ad/otp library. It shows validation with the correct challenge and an example of failed validation using an incorrect challenge. The `ValidateOCRA` function verifies if a given code matches the expected response for a specific secret, OCRA suite, and input parameters. Ensure the 'github.com/ja7ad/otp' package is imported.

```go
package main

import (
    "fmt"
    "log"
    "github.com/ja7ad/otp"
)

func main() {
    secret := "JBSWY3DPEHPK3PXP"
    suite := otp.MustRawSuite("OCRA-1:HOTP-SHA1-6:QN08")
    challenge := []byte("87654321")

    // Generate a code
    code, err := otp.GenerateOCRA(secret, suite, otp.OCRAInput{
        Challenge: challenge,
    })
    if err != nil {
        log.Fatal(err)
    }

    // Validate the code with same challenge
    valid, err := otp.ValidateOCRA(secret, code, suite, otp.OCRAInput{
        Challenge: challenge,
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("OCRA Validation: %v\n", valid)

    // Invalid validation with different challenge
    invalidValid, err := otp.ValidateOCRA(secret, code, suite, otp.OCRAInput{
        Challenge: []byte("11111111"),
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("OCRA Validation (Wrong Challenge): %v\n", invalidValid)

    // Output example:
    // OCRA Validation: true
    // OCRA Validation (Wrong Challenge): false
}
```

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

### Run Benchmark Tests

Source: https://github.com/ja7ad/otp/blob/main/otp-js/README.md

Initiates the benchmark tests for the otp-js library using npm. This command helps in evaluating the performance of different algorithms and operations within the library.

```bash
npm run benchmark
```

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

### Generate Random Secret via API

Source: https://context7.com/ja7ad/otp/llms.txt

Provides an HTTP GET endpoint for generating random OTP secrets. You can specify the desired hashing algorithm (SHA1, SHA256, SHA512) as a query parameter. The response includes the generated secret and the algorithm used.

```bash
# Generate secret with default algorithm (SHA1)
curl -X GET http://localhost:8080/otp/secret

# Response:
# {
#   "secret": "JBSWY3DPEHPK3PXP",
#   "algorithm": "SHA1"
# }

# Generate secret with SHA256
curl -X GET "http://localhost:8080/otp/secret?algorithm=SHA256"

# Response:
# {
#   "secret": "GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ",
#   "algorithm": "SHA256"
# }

# Generate secret with SHA512
curl -X GET "http://localhost:8080/otp/secret?algorithm=SHA512"

# Response:
# {
#   "secret": "MFRGGZDFMZTWQ2LKNNWG23TPOAFRGC4DINFXGK5DINFXGK5DINFXGK5DINFXGK5DINFXGK5DIN",
#   "algorithm": "SHA512"
# }

```

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

### Run Unit Tests

Source: https://github.com/ja7ad/otp/blob/main/otp-js/README.md

Executes the unit tests for the otp-js library using npm. This command is used to verify the correctness of the library's functionality.

```bash
npm test
```

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

### List OCRA Suites

Source: https://context7.com/ja7ad/otp/llms.txt

Retrieves a list of all supported OCRA suites.

```APIDOC
## GET /ocra/suites

### Description
Lists all supported OCRA suites.

### Method
GET

### Endpoint
`/ocra/suites`

### Parameters
None

### Request Example
```bash
curl -X GET http://localhost:8080/ocra/suites
```

### Response
#### Success Response (200)
- **suites** (array of strings) - A list of available OCRA suite strings.

#### Response Example
```json
{
  "suites": [
    "OCRA-1:HOTP-SHA1-6:QN08",
    "OCRA-1:HOTP-SHA256-8:C-QN08-PSHA1",
    "OCRA-1:HOTP-SHA512-8:QN08-T1M"
  ]
}
```
```

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

### List OCRA Suites (Go)

Source: https://context7.com/ja7ad/otp/llms.txt

Provides functionality to list all predefined OCRA suite configurations supported by the 'github.com/ja7ad/otp' package and to check if a specific OCRA suite is known. It iterates through available suites and prints their names, and also checks the validity of custom suite strings.

```go
package main

import (
    "fmt"
    "github.com/ja7ad/otp"
)

func main() {
    // Get all supported OCRA suites
    suites := otp.ListSuites()

    fmt.Println("Available OCRA Suites:")
    for i, suite := range suites {
        fmt.Printf("%d. %s\n", i+1, suite)
    }

    // Check if a specific suite is supported
    customSuite := "OCRA-1:HOTP-SHA256-8:C-QN08-PSHA1"
    if otp.IsKnownSuite(customSuite) {
        fmt.Printf("\n%s is supported\n", customSuite)
    }

    // Output example:
    // Available OCRA Suites:
    // 1. OCRA-1:HOTP-SHA1-6:QN08
    // 2. OCRA-1:HOTP-SHA256-8:C-QN08-PSHA1
    // 3. OCRA-1:HOTP-SHA512-8:QN08-T1M
    // ... (more suites)
    // 
    // OCRA-1:HOTP-SHA256-8:C-QN08-PSHA1 is supported
}
```

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

### Generate OTP URLs (Go)

Source: https://context7.com/ja7ad/otp/llms.txt

Generates otpauth:// URLs for TOTP and HOTP, compatible with authenticator apps like Google Authenticator. Requires the 'github.com/ja7ad/otp' package. Input includes issuer, secret, account name, and security parameters like period, digits, and algorithm. Outputs a string representation of the URL.

```go
package main

import (
    "fmt"
    "log"
    "github.com/ja7ad/otp"
)

func main() {
    // Generate a secret
    secret, err := otp.RandomSecret(otp.SHA1)
    if err != nil {
        log.Fatal(err)
    }

    // Generate TOTP URL for Google Authenticator
    totpURL, err := otp.GenerateTOTPURL(otp.URLParam{
        Issuer:      "MyApp",
        Secret:      secret,
        AccountName: "user@example.com",
        Period:      30,
        Digits:      otp.SixDigits,
        Algorithm:   otp.SHA1,
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("TOTP URL: %s\n", totpURL.String())

    // Generate HOTP URL
    hotpURL, err := otp.GenerateHOTPURL(otp.URLParam{
        Issuer:      "MyApp",
        Secret:      secret,
        AccountName: "user@example.com",
        Digits:      otp.EightDigits,
        Algorithm:   otp.SHA256,
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("HOTP URL: %s\n", hotpURL.String())

    // Output example:
    // TOTP URL: otpauth://totp/MyApp:user@example.com?algorithm=SHA1&digits=6&issuer=MyApp&period=30&secret=JBSWY3DPEHPK3PXP
    // HOTP URL: otpauth://hotp/MyApp:user@example.com?algorithm=SHA256&counter=0&digits=8&issuer=MyApp&secret=JBSWY3DPEHPK3PXP
}
```

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

### Parse OCRA Suite Configuration in Go

Source: https://context7.com/ja7ad/otp/llms.txt

Parses raw OCRA suite strings into a structured configuration object. It uses the 'github.com/ja7ad/otp' package to handle the parsing and validation. The function 'SuiteConfigFromRaws' takes a raw suite string as input and returns a 'SuiteConfig' object. It also demonstrates how to create and validate an OTP suite from the configuration.

```go
package main

import (
    "fmt"
    "github.com/ja7ad/otp"
)

func main() {
    // Parse raw OCRA suite string
    rawSuite := "OCRA-1:HOTP-SHA256-8:C-QN08-PSHA1"
    config := otp.SuiteConfigFromRaws(rawSuite)

    fmt.Printf("Raw Suite: %s\n", rawSuite)
    fmt.Printf("Hash Algorithm: %s\n", config.Hash.String())
    fmt.Printf("Code Digits: %d\n", config.Digits)
    fmt.Printf("Include Counter: %v\n", config.IncludeCounter)
    fmt.Printf("Include Challenge: %v\n", config.IncludeChallenge)
    fmt.Printf("Include Password: %v\n", config.IncludePassword)
    fmt.Printf("Challenge Format: %d\n", config.Challenge)
    fmt.Printf("Password Hash: %d\n", config.PasswordHash)

    // Create a suite from config
    suite, err := otp.NewSuite(config)
    if err != nil {
        fmt.Printf("Error: %v\n", err)
        return
    }

    fmt.Printf("\nSuite String: %s\n", suite.String())

    // Validate suite
    if err := suite.Validate(); err != nil {
        fmt.Printf("Validation Error: %v\n", err)
    } else {
        fmt.Println("Suite is valid")
    }

    // Output example:
    // Raw Suite: OCRA-1:HOTP-SHA256-8:C-QN08-PSHA1
    // Hash Algorithm: SHA256
    // Code Digits: 8
    // Include Counter: true
    // Include Challenge: true
    // Include Password: true
    // Challenge Format: 1
    // Password Hash: 1
    //
    // Suite String: OCRA-1:HOTP-SHA256-8:C-QN08-PSHA1
    // Suite is valid
}

```

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

### Parse OCRA Suite

Source: https://context7.com/ja7ad/otp/llms.txt

Parses an OCRA suite string and returns its configuration details.

```APIDOC
## POST /ocra/suite

### Description
Parses an OCRA suite string.

### Method
POST

### Endpoint
`/ocra/suite`

### Parameters
#### Request Body
- **raw_suite** (string) - Required - The OCRA suite string to parse.

### Request Example
```json
{
  "raw_suite": "OCRA-1:HOTP-SHA256-8:C-QN08-PSHA1"
}
```

### Response
#### Success Response (200)
- **raw** (string) - The original raw OCRA suite string.
- **config** (object) - The parsed configuration of the OCRA suite.
  - **hash_function** (string) - The hashing algorithm.
  - **code_digits** (integer) - The number of digits in the code.
  - **challenge_format** (integer) - The format of the challenge.
  - **include_counter** (boolean) - Whether a counter is included.
  - **include_challenge** (boolean) - Whether the challenge is included.
  - **include_password** (boolean) - Whether a password is included.
  - **password_hash** (integer) - The password hashing method.
  - **timestep** (integer) - The time step if applicable.

#### Response Example
```json
{
  "raw": "OCRA-1:HOTP-SHA256-8:C-QN08-PSHA1",
  "config": {
    "hash_function": "SHA256",
    "code_digits": 8,
    "challenge_format": 1,
    "include_counter": true,
    "include_challenge": true,
    "include_password": true,
    "password_hash": 1,
    "timestep": 0
  }
}
```
```

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

### Initialize WASM Runtime and Generate TOTP

Source: https://github.com/ja7ad/otp/blob/main/otp-js/README.md

Demonstrates how to initialize the WebAssembly runtime provided by otp-js and then use it to generate a Time-based One-Time Password (TOTP). It requires the secret key, current timestamp, desired number of digits, hashing algorithm, and an optional period.

```javascript
const initWasm = require("otp-js");

(async () => {
  const otp = await initWasm();

  const code = otp.generateTOTP("JBSWY3DPEHPK3PXP", Math.floor(Date.now() / 1000), "6", "SHA1", 30);
  console.log("TOTP:", code);
})();
```

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

### Generate and Validate HOTP using Ja7ad/otp

Source: https://github.com/ja7ad/otp/blob/main/README.md

This Go code demonstrates generating a random secret, creating a Hash-based One-Time Password (HOTP) code, and validating it using a counter. It also shows the generation of an HOTP URL. This functionality requires the 'github.com/ja7ad/otp' library.

```go
package main

import (
	"fmt"
	"github.com/ja7ad/otp"
	"log"
)

func main() {
	secret, err := otp.RandomSecret(otp.SHA1)
	if err != nil {
		log.Fatal(err)
	}

	counter := uint64(1)

	code, err := otp.GenerateHOTP(secret, counter, otp.DefaultHOTPParam)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(code)

	ok, err := otp.ValidateHOTP(secret, code, counter, otp.DefaultHOTPParam)
	if err != nil {
		log.Fatal(err)
	}

	if !ok {
		log.Fatal("Invalid OTP")
	}

	url, err := otp.GenerateHOTPURL(otp.URLParam{
		Issuer:      "https://example.com",
		Secret:      secret,
		AccountName: "foobar",
		Period:      otp.DefaultHOTPParam.Period,
		Digits:      otp.DefaultHOTPParam.Digits,
		Algorithm:   otp.DefaultHOTPParam.Algorithm,
	})
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(url.String())
}
```

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

### Generate and Validate TOTP using Ja7ad/otp

Source: https://github.com/ja7ad/otp/blob/main/README.md

This Go code snippet demonstrates how to generate a random secret, create a Time-based One-Time Password (TOTP) code, and validate it against the provided secret and time. It also shows how to generate a TOTP URL for provisioning authenticator apps. Requires the 'github.com/ja7ad/otp' library.

```go
package main

import (
	"fmt"
	"github.com/ja7ad/otp"
	"log"
	time "time"
)

func main() {
	secret, err := otp.RandomSecret(otp.SHA1)
	if err != nil {
		log.Fatal(err)
	}

	t := time.Now()

	code, err := otp.GenerateTOTP(secret, t, otp.DefaultTOTPParam)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(code)

	ok, err := otp.ValidateTOTP(secret, code, t, otp.DefaultTOTPParam)
	if err != nil {
		log.Fatal(err)
	}

	if !ok {
		log.Fatal("Invalid OTP")
	}

	url, err := otp.GenerateTOTPURL(otp.URLParam{
		Issuer:      "https://example.com",
		Secret:      secret,
		AccountName: "foobar",
		Period:      otp.DefaultTOTPParam.Period,
		Digits:      otp.DefaultTOTPParam.Digits,
		Algorithm:   otp.DefaultTOTPParam.Algorithm,
	})
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(url.String())
}
```

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

### Generate OTP URL via API

Source: https://context7.com/ja7ad/otp/llms.txt

Generates an otpauth:// URL, which can be used to configure authenticator apps.

```APIDOC
## GET /otp/url

### Description
Generates an otpauth:// URL for configuring authenticator apps.

### Method
GET

### Endpoint
/otp/url

### Parameters
#### Query Parameters
- **type** (string) - Required - The type of OTP ('totp' or 'hotp').
- **secret** (string) - Required - The secret key for OTP generation.
- **issuer** (string) - Optional - The issuer name for the authenticator app.
- **label** (string) - Optional - The label for the account (e.g., username).
- **algorithm** (string) - Optional - The hashing algorithm (e.g., "SHA1", "SHA256"). Defaults to "SHA1" for TOTP, and "SHA1" for HOTP.
- **digits** (string) - Optional - The number of digits in the OTP code. Defaults to "6".
- **period** (integer) - Optional - The time period in seconds for TOTP. Defaults to 30.
- **counter** (integer) - Optional - The counter value for HOTP. Required if type is 'hotp'.

### Request Example
```bash
# Generate TOTP URL
curl -X GET "http://localhost:8080/otp/url?type=totp&secret=JBSWY3DPEHPK3PXP&issuer=MyApp&label=user@example.com"

# Generate HOTP URL
curl -X GET "http://localhost:8080/otp/url?type=hotp&secret=JBSWY3DPEHPK3PXP&issuer=MyApp&label=user@example.com&counter=42"
```

### Response
#### Success Response (200)
- **url** (string) - The generated otpauth:// URL.

#### Response Example
```json
{
  "url": "otpauth://totp/MyApp:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=MyApp&algorithm=SHA1&digits=6&period=30"
}
```
```

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

### List available OCRA suites using curl

Source: https://context7.com/ja7ad/otp/llms.txt

Retrieves a list of all supported OCRA suites. This endpoint is useful for understanding the available configuration options for OCRA codes. The response is a JSON object containing an array of suite strings.

```bash
curl -X GET http://localhost:8080/ocra/suites
```

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

### Generate OCRA with raw suite string using curl

Source: https://context7.com/ja7ad/otp/llms.txt

Generates an OCRA (Open Authentication) code using a raw suite string. This method requires the secret key, the raw suite string defining the OCRA parameters, and the input, which includes a challenge. The response provides the generated OCRA code and the suite used.

```bash
curl -X POST http://localhost:8080/ocra/generate \
  -H "Content-Type: application/json" \
  -d '{
    "secret": "JBSWY3DPEHPK3PXP",
    "raw_suite": "OCRA-1:HOTP-SHA1-6:QN08",
    "input": {
      "challenge_hex": "3132333435363738"
    }
  }'
```

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

### OTP API Endpoints

Source: https://github.com/ja7ad/otp/blob/main/README.md

This section details the available API endpoints for generating and validating various types of one-time passwords (TOTP, HOTP, OCRA) and managing OTP secrets and URLs.

```APIDOC
## POST /totp/generate

### Description
Generates a Time-based One-Time Password (TOTP) code.

### Method
POST

### Endpoint
/totp/generate

### Parameters
#### Request Body
- **secret** (string) - Required - The base32 encoded secret key.
- **digits** (integer) - Optional - The desired length of the OTP code (default is 6, options are 6, 8, 10).
- **interval** (integer) - Optional - The time step in seconds for the TOTP code (default is 30).
- **algorithm** (string) - Optional - The HMAC algorithm to use (e.g., SHA1, SHA256, SHA512; default is SHA1).

### Request Example
```json
{
  "secret": "JBSWY3DPEHPK3PXP",
  "digits": 8,
  "interval": 60
}
```

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

#### Response Example
```json
{
  "code": "12345678"
}
```

## POST /totp/validate

### Description
Validates a Time-based One-Time Password (TOTP) code.

### Method
POST

### Endpoint
/totp/validate

### Parameters
#### Request Body
- **secret** (string) - Required - The base32 encoded secret key.
- **code** (string) - Required - The TOTP code to validate.
- **digits** (integer) - Optional - The length of the OTP code (must match the generated code's length).
- **interval** (integer) - Optional - The time step in seconds used for generation (default is 30).
- **skew** (integer) - Optional - The allowed time skew in seconds for validation (default is 0).
- **algorithm** (string) - Optional - The HMAC algorithm used for generation (default is SHA1).

### Request Example
```json
{
  "secret": "JBSWY3DPEHPK3PXP",
  "code": "12345678",
  "skew": 30
}
```

### Response
#### Success Response (200)
- **valid** (boolean) - True if the code is valid, false otherwise.

#### Response Example
```json
{
  "valid": true
}
```

## POST /hotp/generate

### Description
Generates a Hash-based One-Time Password (HOTP) code.

### Method
POST

### Endpoint
/hotp/generate

### Parameters
#### Request Body
- **secret** (string) - Required - The base32 encoded secret key.
- **counter** (integer) - Required - The counter value for the HOTP code.
- **digits** (integer) - Optional - The desired length of the OTP code (default is 6, options are 6, 8, 10).
- **algorithm** (string) - Optional - The HMAC algorithm to use (e.g., SHA1, SHA256, SHA512; default is SHA1).

### Request Example
```json
{
  "secret": "JBSWY3DPEHPK3PXP",
  "counter": 10,
  "digits": 8
}
```

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

#### Response Example
```json
{
  "code": "87654321"
}
```

## POST /hotp/validate

### Description
Validates a Hash-based One-Time Password (HOTP) code.

### Method
POST

### Endpoint
/hotp/validate

### Parameters
#### Request Body
- **secret** (string) - Required - The base32 encoded secret key.
- **code** (string) - Required - The HOTP code to validate.
- **counter** (integer) - Required - The current counter value.
- **digits** (integer) - Optional - The length of the OTP code.
- **algorithm** (string) - Optional - The HMAC algorithm used for generation (default is SHA1).

### Request Example
```json
{
  "secret": "JBSWY3DPEHPK3PXP",
  "code": "87654321",
  "counter": 10
}
```

### Response
#### Success Response (200)
- **valid** (boolean) - True if the code is valid, false otherwise.

#### Response Example
```json
{
  "valid": true
}
```

## POST /ocra/generate

### Description
Generates an OCRA (One-time Code Remote Authentication) code.

### Method
POST

### Endpoint
/ocra/generate

### Parameters
#### Request Body
- **secret** (string) - Required - The base32 encoded secret key.
- **suite** (string) - Required - The OCRA suite name (e.g., "OCRA-1v0").
- **question** (string) - Optional - The question string for OCRA-1v0.
- **session_number** (string) - Optional - The session number for OCRA-1v0.
- **counter** (integer) - Optional - The counter value.
- **timestamp** (integer) - Optional - The timestamp in seconds.
- **challenge** (string) - Optional - The challenge string.

### Request Example
```json
{
  "secret": "JBSWY3DPEHPK3PXP",
  "suite": "OCRA-1v0",
  "question": "What is your favorite color?"
}
```

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

#### Response Example
```json
{
  "code": "OCRA123456"
}
```

## POST /ocra/validate

### Description
Validates an OCRA (One-time Code Remote Authentication) code.

### Method
POST

### Endpoint
/ocra/validate

### Parameters
#### Request Body
- **secret** (string) - Required - The base32 encoded secret key.
- **suite** (string) - Required - The OCRA suite name.
- **code** (string) - Required - The OCRA code to validate.
- **question** (string) - Optional - The question string.
- **session_number** (string) - Optional - The session number.
- **counter** (integer) - Optional - The counter value.
- **timestamp** (integer) - Optional - The timestamp in seconds.
- **challenge** (string) - Optional - The challenge string.

### Request Example
```json
{
  "secret": "JBSWY3DPEHPK3PXP",
  "suite": "OCRA-1v0",
  "code": "OCRA123456"
}
```

### Response
#### Success Response (200)
- **valid** (boolean) - True if the code is valid, false otherwise.

#### Response Example
```json
{
  "valid": true
}
```

## GET /otp/secret

### Description
Generates a random, base32 encoded secret key.

### Method
GET

### Endpoint
/otp/secret

### Parameters
#### Query Parameters
- **digits** (integer) - Optional - The desired length of the secret key in bytes (default is 20).
- **algorithm** (string) - Optional - The HMAC algorithm to use (e.g., SHA1, SHA256, SHA512; default is SHA1).

### Response
#### Success Response (200)
- **secret** (string) - The generated base32 encoded secret.

#### Response Example
```json
{
  "secret": "JBSWY3DPEHPK3PXP"
}
```

## POST /otp/url

### Description
Generates an `otpauth://` URL for use with applications like Google Authenticator.

### Method
POST

### Endpoint
/otp/url

### Parameters
#### Request Body
- **secret** (string) - Required - The base32 encoded secret key.
- **type** (string) - Required - The type of OTP (e.g., "totp", "hotp").
- **label** (string) - Required - The label for the account (e.g., "user@example.com").
- **issuer** (string) - Optional - The issuer name (e.g., "MyCompany").
- **digits** (integer) - Optional - The desired length of the OTP code (default is 6).
- **interval** (integer) - Optional - The time step in seconds for TOTP (default is 30).
- **counter** (integer) - Optional - The initial counter value for HOTP.
- **algorithm** (string) - Optional - The HMAC algorithm to use (default is SHA1).

### Request Example
```json
{
  "secret": "JBSWY3DPEHPK3PXP",
  "type": "totp",
  "label": "user@example.com",
  "issuer": "MyCompany"
}
```

### Response
#### Success Response (200)
- **url** (string) - The generated `otpauth://` URL.

#### Response Example
```json
{
  "url": "otpauth://totp/MyCompany:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=MyCompany"
}
```

## GET /ocra/suites

### Description
Lists the supported OCRA suites.

### Method
GET

### Endpoint
/ocra/suites

### Response
#### Success Response (200)
- **suites** (array of strings) - A list of supported OCRA suite names.

#### Response Example
```json
{
  "suites": ["OCRA-1v0", "OCRA-2v0"]
}
```

## POST /ocra/suite

### Description
Parses and describes the configuration of a given OCRA suite.

### Method
POST

### Endpoint
/ocra/suite

### Parameters
#### Request Body
- **suite** (string) - Required - The OCRA suite name.

### Request Example
```json
{
  "suite": "OCRA-1v0"
}
```

### Response
#### Success Response (200)
- **description** (string) - A description of the OCRA suite configuration.

#### Response Example
```json
{
  "description": "OCRA-1v0: HOTP function with SHA1, 6 digits, event-counting, default keyset."
}
```
```

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

### Generate OCRA Codes with /ja7ad/otp in Go

Source: https://context7.com/ja7ad/otp/llms.txt

This Go code snippet shows how to generate OCRA (Challenge-Response Authentication) codes using the /ja7ad/otp library, adhering to RFC 6287. It covers generating random secrets, using predefined OCRA suites, and generating codes with numeric challenges, counters, and password hashes. Ensure the 'github.com/ja7ad/otp' package is imported.

```go
package main

import (
    "fmt"
    "log"
    "github.com/ja7ad/otp"
)

func main() {
    // Generate a secret
    secret, err := otp.RandomSecret(otp.SHA1)
    if err != nil {
        log.Fatal(err)
    }

    // Use a predefined OCRA suite (numeric challenge, 6 digits)
    suite := otp.MustRawSuite("OCRA-1:HOTP-SHA1-6:QN08")

    // Generate OCRA code with 8-digit numeric challenge
    code, err := otp.GenerateOCRA(secret, suite, otp.OCRAInput{
        Challenge: []byte("12345678"),
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("OCRA Code (QN08): %s\n", code)

    // Use suite with counter and challenge
    suiteWithCounter := otp.MustRawSuite("OCRA-1:HOTP-SHA256-8:C-QN08-PSHA1")

    // Prepare input with counter, challenge, and password hash
    input, err := otp.HexInputToOCRA(
        "0000000000000001",  // Counter (hex)
        "3132333435363738",  // Challenge "12345678" (hex)
        "d033e22ae348aeb5660fc2140aec35850c4da997",  // Password hash SHA1 of "password"
        "",  // No session info
        "",  // No timestamp
    )
    if err != nil {
        log.Fatal(err)
    }

    codeComplex, err := otp.GenerateOCRA(secret, suiteWithCounter, input)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("OCRA Code (C-QN08-PSHA1): %s\n", codeComplex)

    // Output example:
    // OCRA Code (QN08): 123456
    // OCRA Code (C-QN08-PSHA1): 12345678
}
```

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

### Generate OCRA Code

Source: https://context7.com/ja7ad/otp/llms.txt

Generates an OCRA (Open Authentication) challenge-response code based on a secret, suite, and input.

```APIDOC
## POST /ocra/generate

### Description
Generates an OCRA challenge-response code.

### Method
POST

### Endpoint
`/ocra/generate`

### Parameters
#### Request Body
- **secret** (string) - Required - The shared secret key.
- **raw_suite** (string) - Required (if `suite` is not provided) - The raw OCRA suite string.
- **suite** (object) - Required (if `raw_suite` is not provided) - Configuration object for the OCRA suite.
  - **hash_function** (string) - Required - The hashing algorithm (e.g., 'SHA1', 'SHA256').
  - **code_digits** (integer) - Required - The number of digits in the generated code.
  - **challenge_format** (integer) - Required - The format of the challenge.
  - **include_counter** (boolean) - Required - Whether to include a counter in the computation.
  - **include_challenge** (boolean) - Required - Whether to include the challenge in the computation.
  - **include_password** (boolean) - Required - Whether to include a password in the computation.
  - **password_hash** (integer) - Required - The hashing method for the password.
- **input** (object) - Required - Input data for the OCRA generation.
  - **challenge_hex** (string) - Required - The challenge data in hexadecimal format.
  - **counter_hex** (string) - Optional - The counter value in hexadecimal format.
  - **password_hex** (string) - Optional - The password hash in hexadecimal format.

### Request Example (raw_suite)
```json
{
  "secret": "JBSWY3DPEHPK3PXP",
  "raw_suite": "OCRA-1:HOTP-SHA1-6:QN08",
  "input": {
    "challenge_hex": "3132333435363738"
  }
}
```

### Request Example (suite config)
```json
{
  "secret": "JBSWY3DPEHPK3PXP",
  "suite": {
    "hash_function": "SHA256",
    "code_digits": 8,
    "challenge_format": 1,
    "include_counter": true,
    "include_challenge": true,
    "include_password": true,
    "password_hash": 1
  },
  "input": {
    "counter_hex": "0000000000000001",
    "challenge_hex": "3132333435363738",
    "password_hex": "d033e22ae348aeb5660fc2140aec35850c4da997"
  }
}
```

### Response
#### Success Response (200)
- **code** (string) - The generated OCRA code.
- **suite** (string) - The OCRA suite string used for generation.

#### Response Example
```json
{
  "code": "123456",
  "suite": "OCRA-1:HOTP-SHA1-6:QN08"
}
```
```

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

### Validate HOTP Codes with /ja7ad/otp in Go

Source: https://context7.com/ja7ad/otp/llms.txt

This Go code snippet illustrates how to validate HMAC-Based One-Time Passwords (HOTP) using the /ja7ad/otp library. It demonstrates validation with an exact counter and with counter skew tolerance. The `ValidateHOTP` function checks if a given code matches the expected OTP for a given secret and counter, potentially within a specified range. Ensure the 'github.com/ja7ad/otp' package is imported.

```go
package main

import (
    "fmt"
    "log"
    "github.com/ja7ad/otp"
)

func main() {
    secret := "JBSWY3DPEHPK3PXP"
    counter := uint64(42)

    // Generate a code
    code, err := otp.GenerateHOTP(secret, counter, otp.DefaultHOTPParam)
    if err != nil {
        log.Fatal(err)
    }

    // Validate with exact counter
    valid, err := otp.ValidateHOTP(secret, code, counter, otp.DefaultHOTPParam)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Exact Counter Validation: %v\n", valid)

    // Validate with counter skew (allows counter ±2)
    paramWithSkew := &otp.Param{
        Digits:    otp.SixDigits,
        Algorithm: otp.SHA1,
        Skew:      2,
    }
    validWithSkew, err := otp.ValidateHOTP(secret, code, counter+1, paramWithSkew)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Counter Skew Validation (counter+1): %v\n", validWithSkew)

    // Output example:
    // Exact Counter Validation: true
    // Counter Skew Validation (counter+1): true
}
```

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

### Parse OTP URLs (Go)

Source: https://context7.com/ja7ad/otp/llms.txt

Parses otpauth:// URL strings into structured OTP parameters, supporting both TOTP and HOTP formats. It utilizes the 'github.com/ja7ad/otp' package and Go's standard 'net/url' package. The function takes a URL object as input and returns a map of parameters or an error.

```go
package main

import (
    "fmt"
    "log"
    "net/url"
    "github.com/ja7ad/otp"
)

func main() {
    // Parse a TOTP URL
    totpURLString := "otpauth://totp/Example:alice@google.com?secret=JBSWY3DPEHPK3PXP&issuer=Example&algorithm=SHA1&digits=6&period=30"
    parsedURL, err := url.Parse(totpURLString)
    if err != nil {
        log.Fatal(err)
    }

    params, err := otp.ParseOTPAuthURL(parsedURL)
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Issuer: %s\n", params.Issuer)
    fmt.Printf("Account: %s\n", params.AccountName)
    fmt.Printf("Secret: %s\n", params.Secret)
    fmt.Printf("Algorithm: %s\n", params.Algorithm.String())
    fmt.Printf("Digits: %d\n", params.Digits)
    fmt.Printf("Period: %d\n", params.Period)

    // Parse a HOTP URL
    hotpURLString := "otpauth://hotp/Example:bob@google.com?secret=GEZDGNBVGY3TQOJQ&issuer=Example&algorithm=SHA256&digits=8&counter=42"
    parsedHOTPURL, err := url.Parse(hotpURLString)
    if err != nil {
        log.Fatal(err)
    }

    hotpParams, err := otp.ParseOTPAuthURL(parsedHOTPURL)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("\nHOTP Issuer: %s\n", hotpParams.Issuer)
    fmt.Printf("HOTP Account: %s\n", hotpParams.AccountName)

    // Output example:
    // Issuer: Example
    // Account: alice@google.com
    // Secret: JBSWY3DPEHPK3PXP
    // Algorithm: SHA1
    // Digits: 6
    // Period: 30
    // 
    // HOTP Issuer: Example
    // HOTP Account: bob@google.com
}
```

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

### Generate OCRA with suite config using curl

Source: https://context7.com/ja7ad/otp/llms.txt

Generates an OCRA code using a detailed suite configuration object. This method allows specifying hash function, code digits, and various input parameters like challenge, counter, and password. The response includes the generated OCRA code and the derived suite string.

```bash
curl -X POST http://localhost:8080/ocra/generate \
  -H "Content-Type: application/json" \
  -d '{
    "secret": "JBSWY3DPEHPK3PXP",
    "suite": {
      "hash_function": "SHA256",
      "code_digits": 8,
      "challenge_format": 1,
      "include_counter": true,
      "include_challenge": true,
      "include_password": true,
      "password_hash": 1
    },
    "input": {
      "counter_hex": "0000000000000001",
      "challenge_hex": "3132333435363738",
      "password_hex": "d033e22ae348aeb5660fc2140aec35850c4da997"
    }
  }'
```

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

### Generate HOTP via API

Source: https://context7.com/ja7ad/otp/llms.txt

Generates a Hash-based One-Time Password (HOTP) code. You can specify parameters like secret, counter, algorithm, and digits.

```APIDOC
## POST /hotp/generate

### Description
Generates a Hash-based One-Time Password (HOTP) code.

### Method
POST

### Endpoint
/hotp/generate

### Parameters
#### Request Body
- **secret** (string) - Required - The secret key for OTP generation.
- **counter** (integer) - Required - The counter value for HOTP generation.
- **algorithm** (string) - Optional - The hashing algorithm to use (e.g., "SHA1", "SHA256", "SHA512"). Defaults to "SHA1".
- **digits** (string) - Optional - The number of digits in the OTP code. Defaults to "6".

### Request Example
```json
{
  "secret": "JBSWY3DPEHPK3PXP",
  "counter": 42,
  "algorithm": "SHA1",
  "digits": "6"
}
```

### Response
#### Success Response (200)
- **code** (string) - The generated HOTP code.
- **counter** (integer) - The counter value used for generation.

#### Response Example
```json
{
  "code": "123456",
  "counter": 42
}
```
```