Low-level, identity-agnostic cryptographic primitives for authenticated encryption of structured and binary data (Web2 & Web3).
npm install @dbrix/core@dbrix/core provides a minimal and security-focused encryption layer built on NaCl secretbox (XSalsa20-Poly1305).
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)