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.
pnpm 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.
import { createHash } from "@better-auth/utils/hash"
const hashBuffer = await createHash("SHA-256").digest("text");
const hashInHex = await createHash("SHA-256", "hex").digest("text");
To encode output in base64
const 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.
import { createHMAC } from './hmac';
const 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.
const secretKey = "my-secret-key"; // Can also be a buffer or TypedArray
const 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.
const key = await hmac.importKey("my-secret-key");
const signature = await hmac.sign(key, "text to sign");
console.log(signature); // Encoded based on the selected encoding format (e.g., hex)
You could also directly sign using the raw string secret key.
const signature2 = await hmac.sign("secret-key",{
data: "text"
});
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.
const key = await hmac.importKey("my-secret-key");
const isValid = await hmac.verify(key, "text to sign", signature);
console.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.
- first create a random string generator with desired charset.
import { createRandomStringGenerator } from "@better-auth/utils/random"
export const generateRandomString = createRandomStringGenerator("A-Z", "0-9", "a-z", "-_")
- generate random string based on length.
const randomString = generateRandomString(32)
const 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
.
import { rsa } from "@better-auth/utils/rsa";
const keyPair = await rsa.generateKeyPair(2048, "SHA-256");
const { publicKey, privateKey } = keyPair;
Exporting Keys
Export a public or private key in your preferred format.
const jwk = await rsa.exportKey(publicKey, "jwk");
const spki = await rsa.exportKey(publicKey, "spki");
Importing Keys
Import a key in the jwk
format for specific usage (encrypt
, decrypt
, sign
, or verify
).
const importedKey = await rsa.importKey(jwk, "encrypt");
Encryption
Encrypt sensitive data using an RSA public key. Input can be a string, ArrayBuffer
, TypedArray
or string
.
const encryptedData = await rsa.encrypt(publicKey, "Sensitive data");
Decryption
Decrypt encrypted data using the corresponding RSA private key.
const decryptedData = await rsa.decrypt(privateKey, encryptedData);
const originalText = new TextDecoder().decode(decryptedData);
Signing
Sign a message using the RSA private key. Input can be a string, ArrayBuffer
, or TypedArray
.
const signature = await rsa.sign(privateKey, "Message to sign");
Verifying
Verify a signature against the original data using the RSA public key.
const isValid = await rsa.verify(publicKey, {
signature,
data: "Message to sign",
});
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"
.
import { ecdsa } from "@better-auth/utils/ecdsa";
const { privateKey, publicKey } = await ecdsa.generateKeyPair("P-256");
Exporting Keys
Export a public or private key in your preferred format, such as pkcs8
or spki
.
const exportedPrivateKey = await ecdsa.exportKey(privateKey, "pkcs8");
const 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.
const importedPrivateKey = await ecdsa.importPrivateKey(exportedPrivateKey, "P-256");
const 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"
.
const 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"
).
const isValid = await ecdsa.verify(publicKey, {
signature,
data: "Message to verify",
hash: "SHA-256",
});
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.
import { createOTP } from "@better-auth/utils/otp";
const secret = "my-super-secret-key";
const counter = 1234;
const otp = createOTP(secret, {
digits: 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.
import { createOTP } from "@better-auth/utils/otp";
const secret = "my-super-secret-key"
const otp = createOTP(secret, {
digits: 6,
period: 30,
}).totp();
Verifying TOTP
Verify a TOTP against the secret key and a specified time window. The default time window is 30 seconds.
import { createOTP } from "@better-auth/utils/otp";
const secret = "my-super-secret-key"
const isValid = createOTP(secret, {
digits: 6,
period: 30,
}).verify(otp);
You can also specify the time window in seconds.
import { createOTP } from "@better-auth/utils";
const 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.
import { createOTP } from "@better-auth/utils/otp";
const secret = "my-super-secret-key";
const 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
.
import { base64 } from "@better-auth/utils/base64";
const encodedData = base64.encode("Data to encode");
options:
padding
- Include padding characters (=
) at the end of the encoded string
const encodedData = base64.encode("Data to encode", { url: true, padding: false });
Decoding
Decode base64-encoded data. Input can be a string or ArrayBuffer
.
const decodedData = await base64.decode(encodedData);
It automatically detects if the input is URL-safe and includes padding characters.
Base64Url
Url safe alternative
import { base64Url } from "@better-auth/utils/base64";
const 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
.
import { hex } from "@better-auth/utils/hex";
const encodedData = hex.encode("Data to encode");
Decoding
Decode hexadecimal-encoded data. Input can be a string or ArrayBuffer
.
const 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
import { binary } from "@better-auth/util/binary"
const data = binary.encode("Hello World!")
Decoding
import { binary } from "@better-auth/util/binary"
const data = binary.decode(new Unit8Array([[72, 101, 108, 108, 111]]))
License
MIT