Sekret

Sekret is a small wrapper around the Web Crypto API for password-based encryption and decryption.

It exposes a minimal API:

• encrypt(message, password, options?)
• decrypt(encryptedMessage, password)
• version

Installation

Using npm:

npm install @lamartinecabral/sekret

Browser via CDN:

<script src="https://unpkg.com/@lamartinecabral/sekret"></script>

That script exposes a global named Sekret.

<script>
  Sekret.encrypt("Hello World!", "1234").then(console.log);
</script>

ES modules via CDN:

<script type="module">
  import Sekret from "https://unpkg.com/@lamartinecabral/sekret/dist/index.esm.js";
</script>

Runtime requirements

Sekret depends on Web Crypto globals such as crypto.subtle, TextEncoder, TextDecoder, atob, and btoa.

• Modern browsers are supported.
• Recent Node.js versions with Web Crypto support are supported.

How it works

Sekret derives a 256-bit AES-GCM key from the provided password using PBKDF2 with SHA-256. Each encrypted payload contains its salt, IV, and ciphertext, so it can be passed directly to decrypt together with the same password.

By default, each encryption call generates:

• a random 16-byte salt
• a random 12-byte IV

This randomized mode means encrypting the same message with the same password produces different output each time.

Set deterministic: true when the same message and password must produce the same output. In that mode, Sekret uses a fixed 16-byte salt and a deterministic 12-byte IV derived from the message. Deterministic encryption can reveal when the same plaintext is encrypted repeatedly, so use the default randomized mode unless deterministic output is required.

The returned value is a Base64 payload containing salt + iv + ciphertext.

Basic usage

You can use the default export:

import Sekret from "@lamartinecabral/sekret";

const message = "Hello World!";
const password = "1234";

const encrypted = await Sekret.encrypt(message, password);
const decrypted = await Sekret.decrypt(encrypted, password);

console.log(encrypted);
console.log(decrypted === message);

Or use named exports:

import { encrypt, decrypt } from "@lamartinecabral/sekret";

const encrypted = await encrypt("Hello World!", "1234");
const decrypted = await decrypt(encrypted, "1234");

API

encrypt(message, password, options?)

Encrypts a UTF-8 string and returns a Base64-encoded payload.

• message: string
• password: string
• options.deterministic: boolean, defaults to false
• returns: Promise<string>

The payload includes the salt and IV required for decryption. By default, a random salt and IV are used, so encrypting the same message with the same password returns different payloads.

To request deterministic encryption:

const encrypted = await Sekret.encrypt("Hello World!", "1234", {
  deterministic: true,
});

With deterministic: true, encrypting the same message with the same password returns the same payload.

decrypt(encryptedMessage, password)

Decrypts a Base64-encoded payload produced by Sekret.

• encryptedMessage: string
• password: string
• returns: Promise<string>

Throws if the password is wrong or the payload is invalid/corrupted.

version

Exposes the package version injected during packaging.

Development

npm test
npm start