🧱 @dbrix/core

Low-level, identity-agnostic cryptographic primitives for authenticated data encryption.

@dbrix/core provides a minimal and security-focused encryption layer built on NaCl secretbox (XSalsa20-Poly1305).

It enables safe encryption of:

- Strings
- JSON / structured data
- Binary payloads

using a derived 32-byte secret key, without exposing metadata in plaintext.

This package is intentionally low-level and works equally well in Web2 and Web3 applications.

---

✨ Features

- Strong authenticated encryption (XSalsa20-Poly1305)
- Automatic type recovery (string / JSON / bytes)
- Encrypted type metadata (no plaintext hints)
- Explicit, defensive error handling
- Payload size limits (DoS-aware)
- Runtime-agnostic (Node, Bun, browsers\*)

---

📦 Installation

``bash
npm install @dbrix/core
`

---

🔐 Basic Usage

`javascript
// test/core_crypto.test.ts
import { encrypt, decrypt } from "@dbrix/core";

/**
* Example secret
* This can come from:
* - Wallet private key (base58)
* - Derived password key
* - Environment secret
*/
const SECRET_KEY_BASE58 =
"2VVjCw4pu6J1VWhmqP8F6NAC1yArzj7D7yDXQrTZUyBfUPyPWoZKv87K5fCL5vqZvWVrsjAZVsVHYZ1vvj6YriVx";

// Example JSON payload
const JSON_DATA = {
userId: "user_123",
email: "test@example.com",
balance: 1500.75,
roles: ["admin", "editor"],
active: true,
};

// Example string payload
const STRING_DATA = "im building my first npm package 🚀";

function runTest() {
console.log("\n=== JSON Encryption Test ===\n");

const encryptedJson = encrypt(JSON_DATA, SECRET_KEY_BASE58);
console.log("Encrypted JSON:", encryptedJson);
// Example output:
// {
// data: "Yi+NnbJDyKx6Sf0Q/Uv1wmSIuTp9L4VMWWPo+Y09ZT/SMJOVE0LTzBjNo4kwgYGIIfx4f/QNooDMrwxK8pfsZHqkDa02MTYjrME/9hWQYwfOdwDaaKH2dj7zkZD/cw4ojGGC/9oR8CdyF8Wws5QtiKht+GLAkuJN69hg6g==",
// nonce: "UOe+ccBSpFcfOjqCYI2jQ8N+c+sGKznw"
// }

const decryptedJson =
decrypt(encryptedJson, SECRET_KEY_BASE58);

console.log("Decrypted JSON:", decryptedJson);
// Example output:
// {
// userId: "user_123",
// email: "test@example.com",
// balance: 1500.75,
// roles: ["admin", "editor"],
// active: true
// }

console.log(
"Match:",
JSON.stringify(decryptedJson) === JSON.stringify(JSON_DATA) ? "✅" : "❌"
);
// Example output:
// Match: ✅

console.log("\n=== String Encryption Test ===\n");

const encryptedString = encrypt(STRING_DATA, SECRET_KEY_BASE58);
console.log("Encrypted String:", encryptedString);
// Example output:
// {
// data: "R9VJ5kKkzY4fN+q3F9kqz9VnF+0+JH1xJ3rZy1E=",
// nonce: "y4FJ9m2C1k+0eJ2QF5P8kJ4ZqXcYB1aR"
// }

const decryptedString = decrypt(encryptedString, SECRET_KEY_BASE58);
console.log("Decrypted String:", decryptedString);
// Example output:
// "im building my first npm package 🚀"

console.log("Match:", decryptedString === STRING_DATA ? "✅" : "❌");
// Example output:
// Match: ✅
}

runTest();
`

Type information is:

- Embedded
- Encrypted
- Recovered automatically on decrypt

---

🧠 Design Principles

- No identity assumptions
Keys may come from passwords, wallets, APIs, or HSMs.

- No metadata leaks
Payload type is encrypted with the data.

- Explicit failure modes
Errors are descriptive and safe by default.

---

⚠️ Security Notes (Important)

- Never use raw user passwords directly
- Always derive keys using a strong KDF:
- Argon2id (recommended)
- scrypt
- PBKDF2 (high iteration count)
- Treat encrypted payloads as untrusted input
- Never log secrets or derived keys

---

🔗 Related Packages

- @dbrix/ledger — deterministic, fixed-length storage encoding (coming soon)
- @dbrix/vault` — high-level vault orchestration (built on core) (coming soon)

---

📜 License

MIT

debrix-core