You can use the Otp.Seed() static method to generate a 20 bytes (160 bits) HMAC-SHA-1 HEX Secret Key.

You can optionally pass a string as the first and unique argument to the Otp.Seed() method (usually is a 8 digits USB key Serial Number).

1import { Otp } from '@alessiofrittoli/crypto-otp'
2
3const secret = Otp.Seed( '45385623' )

You can use the Otp.GenerateSecretASCII() static method to generate a random ASCII Secret Key.

⚠️ Remember to specify ascii as secret.encoding in the subsequent operations.

1import { Otp } from '@alessiofrittoli/crypto-otp'
2
3const secret = Otp.GenerateSecretASCII()

Sometimes you need your Secret Key in a different encoding (e.g. base32 required for adding the credential to an Authenticator App). You can use the Otp.GetSecrets() static method to retrieve the Secret Key in different encodings.

1import { Otp } from '@alessiofrittoli/crypto-otp'
2
3const { hex, ascii, base64url, base32 } = Otp.GetSecrets( {
4  secret: { key: '2E58D8285025A05094667561B3D1AA4EC9CFAB3B' }
5} )

• See OTP.HOTP.GetTokenOptions for HOTP.GetToken options details.

1import { Hotp, type OTP } from '@alessiofrittoli/crypto-otp'
2
3const options: OTP.HOTP.GetTokenOptions = {
4  secret  : { key: '2E58D8285025A05094667561B3D1AA4EC9CFAB3B' },
5  counter : 256, // current credential counter retrieved from a database.
6}
7
8const token = Hotp.GetToken( options )

• See OTP.HOTP.GetDeltaOptions for Hotp.Verify() options details.

1import { Hotp, type OTP } from '@alessiofrittoli/crypto-otp'
2
3const options: OTP.HOTP.GetDeltaOptions = {
4  secret  : { key: '2E58D8285025A05094667561B3D1AA4EC9CFAB3B' },
5  token   : token, // The token provided by the user.
6  digits  : digits,
7  counter : counter, // The counter should be stored in a database and incremented on each credential verification.
8}
9
10const valid = Hotp.Verify( options ) // true | false

A HOTP is incremented on every usage. You should then stored the incremented counter in a database for future verifications.

• See OTP.HOTP.GetDeltaOptions for Hotp.GetDelta() options details.

1import { Hotp, type OTP } from '@alessiofrittoli/crypto-otp'
2
3const options: OTP.HOTP.GetDeltaOptions = {
4  secret  : { key: '2E58D8285025A05094667561B3D1AA4EC9CFAB3B' },
5  token   : token,        // The token provided by the user.
6  counter : counter + 1,  // The stored counter value in the database + 1.
7}
8
9/**
10 * Returns `0` where the delta is the counter difference between the given token and the current counter + 1.
11 * If `null` the given token is not valid and should not be accepted.
12 * 
13 */
14const delta = Hotp.GetDelta( options )

If the HOTP token is generated multiple times without server validation or if the token is being used on different applications (not recommended but is up to the user what to do with his tokens), the client counter could be different (higher) than the counter stored in the server database. This will lead in synchronization mismatch and unwanted token rejects.

We could then offer to the user the possibility to synchorinze counters.

1import { Hotp, type OTP } from '@alessiofrittoli/crypto-otp'
2
3const options: OTP.HOTP.GetDeltaOptions = {
4  secret  : { key: '2E58D8285025A05094667561B3D1AA4EC9CFAB3B' },
5  token   : token, // The token provided by the user.
6  window  : 500, // window should not be greater than `10` during auth processes. only use high values after user has already been authenticated with a different auth method.
7  counter : counterStoredInDatabase,
8}
9
10const delta   = Hotp.GetDelta( options )
11const counter = options.counter // if delta is `null`, store the counter and use it in the next attempt.

1import { Totp, type OTP } from '@alessiofrittoli/crypto-otp'
2
3const options: OTP.TOTP.GetTokenOptions = {
4  secret: { key: '2E58D8285025A05094667561B3D1AA4EC9CFAB3B' }
5}
6
7const token = Totp.GetToken( options )

• See OTP.TOTP.GetDeltaOptions for Totp.Verify() options details.

1import { Totp, type OTP } from '@alessiofrittoli/crypto-otp'
2
3const options: OTP.TOTP.GetDeltaOptions = {
4  secret  : { key: '2E58D8285025A05094667561B3D1AA4EC9CFAB3B' },
5  token   : token, // The token provided by the user.
6  digits  : digits,
7}
8
9const valid = Totp.Verify( options ) // true | false

A TOTP is incremented every step time-step seconds. By default, the time-step is 30 seconds. You may change the time-step using the period option, with units in seconds.

• See OTP.TOTP.GetDeltaOptions for Totp.GetDelta() options details.

1import { Totp, type OTP } from '@alessiofrittoli/crypto-otp'
2
3const options: OTP.TOTP.GetDeltaOptions = {
4  secret  : { key: '2E58D8285025A05094667561B3D1AA4EC9CFAB3B' },
5  token   : token,  // The token provided by the user.
6  period  : 60,     // Must be the same to the `period` value used while generating the token.
7}
8
9/**
10 * Returns `0` where the delta is the time step difference between the given token and the current time.
11 * If `null` the given token is not valid and should not be accepted.
12 * 
13 */
14const delta = Totp.GetDelta( options )

If you need to display a counter indicating the remaining time for the TOTP validity you may need to know when the previous generated TOTP code will change.

To do so you can use the Totp.NextTick() method which returns the Date object representing the next time tick for a TOTP counter.

1import { Totp } from '@alessiofrittoli/crypto-otp'
2
3const date = Totp.NextTick()

Verify a HOTP token with counter value 42 and a window of 10. HOTP has a one-sided window, so this will check counter values from 42 to 52, inclusive, and return a delta number representing the difference between the given counter value and the counter position at which the token was found, or null if it was not found within the window.

1const options: OTP.HOTP.GetDeltaOptions = {
2  secret  : { key: '2E58D8285025A05094667561B3D1AA4EC9CFAB3B' },
3  counter : 42,
4  token   : '474687',
5  window  : 10,
6}
7
8const delta = Hotp.GetDelta( options ) // 6

Verify a TOTP token at the current time with a window of 2. Since the default time step is 30 seconds, and TOTP has a two-sided window, this will check tokens between [current time minus two tokens before] and [current time plus two tokens after]. In other words, with a time step of 30 seconds, it will check the token at the current time, plus the tokens at the current time minus 30 seconds, minus 60 seconds, plus 30 seconds, and plus 60 seconds – basically, it will check tokens between a minute ago and a minute from now. It will return a delta number representing the difference between the current time step and the counter position at which the token was found, or null if it was not found within the window.

1const secret: OTP.Secret = { key: '2E58D8285025A05094667561B3D1AA4EC9CFAB3B' }
2const time1 = new Date( '2024-06-10T04:20:00.000Z' ).getTime() / 1000 // 1717993200
3const time2 = time1 + 60 // 1717993260
4
5/**
6 * By way of example, we will force TOTP to return tokens at time `time1` and
7 * at time `time2` (60 seconds ahead, or 2 steps ahead).
8 */
9const token1 = Totp.GetToken( { secret, time: time1 } ) // 289254
10const token2 = Totp.GetToken( { secret, time: time2 } ) // 345152
11
12/**
13 * We can check the time at token 2, with token 1, but use a window of 2.
14 * With a time step of 30 seconds, this will check all tokens from 60 seconds before the time to 60 seconds after the time.
15 * 
16 * The following example will return `-2`. This signifies that the given token, token1, is -2 steps away from the given time,
17 * which means that it is the token for the value at (-2 * time step) = (-2 * 30 seconds) = 60 seconds ago.
18 */
19const delta = Totp.GetDelta( { secret, token: token1, window: 2, time: time2 } )