🧱 @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

npm install @dbrix/core

🔐 Basic Usage

// 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: "[email protected]",
  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<typeof JSON_DATA>(encryptedJson, SECRET_KEY_BASE58);

  console.log("Decrypted JSON:", decryptedJson);
  // Example output:
  // {
  //   userId: "user_123",
  //   email: "[email protected]",
  //   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