@mcbe-mods/crypto

Symmetric encryption for Minecraft Bedrock Edition Script API — XChaCha20-Poly1305 with password/key support.

Designed to pair with @mcbe-mods/protocol for encrypted in-world communication.

Install

npm install @mcbe-mods/crypto

Usage

From password

import { Cipher } from '@mcbe-mods/crypto'
import { Protocol } from '@mcbe-mods/protocol'

const cipher = Cipher.fromPassword('my-shared-secret')
const protocol = new Protocol({ cipher })

protocol.post('bedrock://my-addon/info', 'hello') // automatically encrypted
protocol.on((event) => {
  event.message // automatically decrypted
})

The optional second argument salt lets you scope a password to a specific project. When omitted, it defaults to a salt bound to this monorepo (github.com/mcbe-mods/runtime):

// Default salt (github.com/mcbe-mods/runtime)
Cipher.fromPassword('secret')
// Custom string salt
Cipher.fromPassword('secret', 'my-project-id')
// Custom binary salt
Cipher.fromPassword('secret', new Uint8Array([1, 2, 3, 4]))

Security note: the default salt is tied to this monorepo to prevent accidental key reuse across projects. In production, pass an app-specific salt or manage keys directly via fromKey. Both sides must use the same password + salt combination.

From raw key

const key = new Uint8Array(32).fill(42)
const cipher = Cipher.fromKey(key)

Both sides must use the same password or key for communication to work.

Custom random source

By default, nonces are generated using Math.random(), which is safe for XChaCha20-Poly1305's 192-bit nonce space but not cryptographically secure. You can inject any random bytes function via CipherOptions:

const cipher = Cipher.fromPassword('secret', undefined, {
  randomBytes(size) {
    // Use any available random source
    const buf = new Uint8Array(size)
    for (let i = 0; i < size; i++) {
      buf[i] = (Math.random() * 256) | 0
    }
    return buf
  },
})

This works with both fromPassword and fromKey.

Note: @minecraft/server does not provide a secure random API. If your runtime has access to one (e.g. Web crypto.getRandomValues), you can pass it here.

License

MIT