SingleCrypt Text

Warning

This package uses Uint8Array.prototype.toBase64() and Uint8Array.fromBase64(), which, as of September 2025, are only supported by the latest versions of browsers and Bun. See MDN for compatibility.

A simple, secure, and fast symmetric encryption library that makes use of AES-GCM and modern platform features. It leverages the native Web Crypto API, so it works both in browsers and JavaScript runtimes.

Why AES-GCM?

AES-GCM is extremely fast on modern CPUs, which have dedicated hardware acceleration (AES-NI), in addition to being highly secure and even quantum-resistant (AES-256-GCM).

Installation

Using bun:

bun add singlecrypt-text

Methods

createSymmetricKeyWithText

Creates a symmetric CryptoKey object to be used in the following methods. This method also converts your value key to a SHA-256 hash. It takes two parameters:

1. A string key to be hashed. A 32-byte random string is recommended.
2. A TextEncoder instance, if you want to reuse it (optional).

Returns a Promise<CryptoKey> containing a SHA-256 hash used to encrypt and decrypt strings.

A TypeError may be thrown if there are problems with the string key.

encryptSymmetricallyText

Encrypts a value with a symmetric CryptoKey previously generated. It takes three parameters:

1. A string value to be encrypted.
2. The symmetric key generated with createSymmetricKeyWithText.
3. A TextEncoder instance, if you want to reuse it (optional).

Returns a Promise<string> containing the encrypted value.

A DOMException may be thrown if the key is invalid or if the operation failed (e.g., AES-GCM plaintext longer than 2^39−256 bytes).

decryptSymmetricallyText

Decrypts a value with a symmetric CryptoKey previously generated. It takes three parameters:

1. A string value to be decrypted.
2. The symmetric key generated with createSymmetricKeyWithText.
3. A TextDecoder instance, if you want to reuse it (optional).

Returns a Promise<string> containing the decrypted value.

The following errors may be thrown:

• TypeError: if the first parameter is not a string.
• SyntaxError: if the first parameter contains characters outside the Base64 alphabet.
• DOMException: if the key is invalid or if the operation failed.

Example

Let's say you have a session ID in a server and you want the server to encrypt and store the ID in a cookie.

./lib/session/crypto.ts

import {
  createSymmetricKeyWithText,
  encryptSymmetricallyText,
  decryptSymmetricallyText
} from "singlecrypt-text";

import { getSessionEncryptionKey } from "./lib/crypto/session";


const sessionCryptoKey = await createSymmetricKeyWithText(
  await getSessionEncryptionKey()
);


export async function encryptSessionId(value: string) {
  return await encryptSymmetricallyText(
    value,
    sessionCryptoKey
  );
}

export async function decryptSessionId(value: string) {
  return await decryptSymmetricallyText(
    value,
    sessionCryptoKey
  );
}

Or you can reuse TextEncoder and TextDecoder instances for slightly better performance:

import {
  createSymmetricKeyWithText,
  encryptSymmetricallyText,
  decryptSymmetricallyText
} from "singlecrypt-text";

import { getSessionEncryptionKey } from "./lib/crypto/session";


const textEncoder = new TextEncoder();
const textDecoder = new TextDecoder();

const sessionCryptoKey = await createSymmetricKeyWithText(
  await getSessionEncryptionKey(),
  textEncoder
);


export async function encryptSessionId(value: string) {
  return await encryptSymmetricallyText(
    value,
    sessionCryptoKey,
    textEncoder
  );
}

export async function decryptSessionId(value: string) {
  return await decryptSymmetricallyText(
    value,
    sessionCryptoKey,
    textDecoder
  );
}

And now you can easily encrypt and decrypt session IDs:

// ...
import { encryptSessionId, decryptSessionId } from "./lib/session/crypto";
// ...

const sessionId = await getSessionIdFromDatabase();
const encryptedId = await encryptSessionId(sessionId);  // Now you can safely store it in an HttpOnly cookie
// ...
const decryptedId = await decryptSessionId(encryptedId);
// ...
console.log(sessionId === decryptedId);  // True
// ...

---

Created by SSbit01.