Better Auth Utils

A simple typescript API for common auth utilities like hashing, encryption, encoding, and OTP generation. Built on top of Web Crypto APIs and it wraps over uncrypto to provide a unified API for both Node.js (using the Crypto module) and web environments (using the Web Crypto API) through Conditional Exports.

1pnpm add @better-auth/utils

Utilities at a Glance

utilities provided by @better-auth/utils:

Utility	Description
Hash	Hash inputs using sha family hash functions.
HMAC	Hash inputs using HMAC with a secret key.
Random String	Generate random strings with a specified length and charset.
RSA	Perform encryption, decryption, signing, and verification with RSA keys.
ECDSA	Perform signing and verification with ECDSA keys.
OTP	Generate and verify one-time passwords.
Base64	Encode and decode data in base64 format.
Hex	Encode and decode data in hexadecimal format.
Binary	Encode and decode data in binary format.

Hash

Digest provides a way to hash an input using sha family hash functions. It wraps over crypto.digest and provide utilities to encode output in hex or base 64.

1import { createHash } from "@better-auth/utils/hash"
2
3const hashBuffer = await createHash("SHA-256").digest("text");
4const hashInHex = await createHash("SHA-256", "hex").digest("text");

To encode output in base64

1const hashInBase64 = await createHash("SHA-256", "base64").digest("text");

HMAC

The HMAC utility allows you to securely hash data using a secret key and SHA family hash functions. It provides methods to sign, verify, and create a customized HMAC instance with specific hashing algorithms and encoding formats.

Create HMAC

To create an HMAC instance, use the createHMAC function. You can specify the SHA family algorithm ("SHA-256", "SHA-384", or "SHA-512") and the desired encoding format ("none", "hex", "base64", "base64url", or "base64urlnopad").

It takes a secret key and returns a key object which could be used to sign and verify data.

1import { createHMAC } from './hmac';
2
3const hmac = createHMAC("SHA-256", "hex"); // Customize algorithm and encoding

Import Key

The importKey method takes a secret key (string, buffer, or typed array) and returns a CryptoKey object that can be used for signing and verifying data.

1const secretKey = "my-secret-key"; // Can also be a buffer or TypedArray
2const key = await hmac.importKey(secretKey);

Sign

The sign method takes a secret key (or CryptoKey) and data to generate a signature. If you provide a raw secret key, it will automatically be imported.

1const key = await hmac.importKey("my-secret-key");
2const signature = await hmac.sign(key, "text to sign");
3console.log(signature); // Encoded based on the selected encoding format (e.g., hex)

You could also directly sign using the raw string secret key.

1const signature2 = await hmac.sign("secret-key",{
2    data: "text"
3});

Verify

The verify method checks if a given signature matches the data using the secret key. You can provide either a raw secret key or a CryptoKey.

1const key = await hmac.importKey("my-secret-key");
2const isValid = await hmac.verify(key, "text to sign", signature);
3console.log(isValid); // true or false

Random String

Random crypto secure string generator. It wraps over crypto.getRandomValues and provide utilities to generator based on length and charset.

1. first create a random string generator with desired charset.

1import { createRandomStringGenerator } from "@better-auth/utils/random"
2
3export const generateRandomString = createRandomStringGenerator("A-Z", "0-9", "a-z", "-_") 

2. generate random string based on length.

1const randomString = generateRandomString(32)
2const randomString2 = generateRandomString(32, "A-Z", "0-9") // override charset

RSA

RSA utilities provide a simple interface to work with RSA cryptographic operations, such as generating key pairs, encrypting and decrypting data, and signing and verifying messages.

Key Pair Generation

You can generate RSA key pairs with specified parameters. By default, the modulusLength is 2048 bits and the hash algorithm is SHA-256.

1import { rsa } from "@better-auth/utils/rsa";
2
3const keyPair = await rsa.generateKeyPair(2048, "SHA-256");
4const { publicKey, privateKey } = keyPair;

Exporting Keys

Export a public or private key in your preferred format.

1const jwk = await rsa.exportKey(publicKey, "jwk");
2const spki = await rsa.exportKey(publicKey, "spki");

Importing Keys

Import a key in the jwk format for specific usage (encrypt, decrypt, sign, or verify).

1const importedKey = await rsa.importKey(jwk, "encrypt");

Encryption

Encrypt sensitive data using an RSA public key. Input can be a string, ArrayBuffer, TypedArray or string.

1const encryptedData = await rsa.encrypt(publicKey, "Sensitive data");

Decryption

Decrypt encrypted data using the corresponding RSA private key.

1const decryptedData = await rsa.decrypt(privateKey, encryptedData);
2const originalText = new TextDecoder().decode(decryptedData);

Signing

Sign a message using the RSA private key. Input can be a string, ArrayBuffer, or TypedArray.

1const signature = await rsa.sign(privateKey, "Message to sign");

Verifying

Verify a signature against the original data using the RSA public key.

1const isValid = await rsa.verify(publicKey, {
2  signature,
3  data: "Message to sign",
4});

ECDSA

ECDSA utilities provide a simple interface to perform key pair generation, signing, and verification using elliptic curve cryptography.

Key Pair Generation

You can generate ECDSA key pairs with your preferred curve. Supported curves are "P-256", "P-384", and "P-521".

1import { ecdsa } from "@better-auth/utils/ecdsa";
2
3const { privateKey, publicKey } = await ecdsa.generateKeyPair("P-256");

Exporting Keys

Export a public or private key in your preferred format, such as pkcs8 or spki.

1const exportedPrivateKey = await ecdsa.exportKey(privateKey, "pkcs8");
2const exportedPublicKey = await ecdsa.exportKey(publicKey, "spki");

Importing Keys

Import an ECDSA private or public key in the appropriate format. Public keys can also be provided as strings.

1const importedPrivateKey = await ecdsa.importPrivateKey(exportedPrivateKey, "P-256");
2const importedPublicKey = await ecdsa.importPublicKey(exportedPublicKey, "P-256");

Signing

Sign data using the ECDSA private key. The input can be a string or ArrayBuffer. You can specify the hash algorithm, which defaults to "SHA-256".

1const signature = await ecdsa.sign(privateKey, "Message to sign", "SHA-256");

Verifying

Verify a signature against the original data using the ECDSA public key. Input can be a string or ArrayBuffer. Signature verification requires providing the signature, data, and hash algorithm (default: "SHA-256").

1const isValid = await ecdsa.verify(publicKey, {
2  signature,
3  data: "Message to verify",
4  hash: "SHA-256",
5});

OTP

The OTP utility provides a simple and secure way to generate and verify one-time passwords (OTPs), commonly used in multi-factor authentication (MFA) systems. It includes support for both HOTP (HMAC-based One-Time Password) and TOTP (Time-based One-Time Password) standards.

It's implemented based on RFC 4226 and RFC 6238.

Generating HOTP

HOTP generates a one-time password based on a counter value and a secret key. The counter should be incremented for each new OTP.

1import { createOTP } from "@better-auth/utils/otp";
2const secret = "my-super-secret-key";
3const counter = 1234;
4const otp = createOTP(secret, {
5  digits: 6,
6}).hotp(counter);

Generating TOTP

TOTP generates a one-time password based on the current time and a secret key. The time step is typically 30 seconds.

1import { createOTP } from "@better-auth/utils/otp";
2const secret = "my-super-secret-key"
3const otp = createOTP(secret, {
4  digits: 6,
5  period: 30,
6}).totp();

Verifying TOTP

Verify a TOTP against the secret key and a specified time window. The default time window is 30 seconds.

1import { createOTP } from "@better-auth/utils/otp";
2const secret = "my-super-secret-key"
3const isValid = createOTP(secret, {
4  digits: 6,
5  period: 30,
6}).verify(otp);

You can also specify the time window in seconds.

1import { createOTP } from "@better-auth/utils";
2const isValid = createOTP(secret).verify(otp, { window: 60 });

Generate URL for Authenticator App

Generate a URL for provisioning a TOTP secret key in an authenticator app.

• issuer - The name of the service or app.
• account - The user's email or username.

1import { createOTP } from "@better-auth/utils/otp";
2
3const secret = "my-super-secret-key";
4const qrCodeUrl = createOTP(secret).url("my-app", "user@email.com"); 

Base64

Base64 utilities provide a simple interface to encode and decode data in base64 format.

Encoding

Encode data in base64 format. Input can be a string, ArrayBuffer, or TypedArray.

1import { base64 } from "@better-auth/utils/base64";
2
3const encodedData = base64.encode("Data to encode");

options:

• padding - Include padding characters (=) at the end of the encoded string

1const encodedData = base64.encode("Data to encode", { url: true, padding: false });

Decoding

Decode base64-encoded data. Input can be a string or ArrayBuffer.

1const decodedData = await base64.decode(encodedData);

It automatically detects if the input is URL-safe and includes padding characters.

Base64Url

Url safe alternative

1import { base64Url } from "@better-auth/utils/base64";
2
3const encodedData = base64Url.encode("Data to encode");

Hex

Hex utilities provide a simple interface to encode and decode data in hexadecimal format.

Encoding

Encode data in hexadecimal format. Input can be a string, ArrayBuffer, or TypedArray.

1import { hex } from "@better-auth/utils/hex";
2
3const encodedData = hex.encode("Data to encode");

Decoding

Decode hexadecimal-encoded data. Input can be a string or ArrayBuffer.

1const decodedData = hex.decode(encodedData);

Binary

A utilities provide a simple interface to encode and decode data in binary format. It uses TextEncode and TextDecoder to encode and decode data respectively.

Encoding

1import { binary } from "@better-auth/util/binary"
2
3const data = binary.encode("Hello World!")

Decoding

1import { binary } from "@better-auth/util/binary"
2
3const data = binary.decode(new Unit8Array([[72, 101, 108, 108, 111]]))

License

MIT