node-rpgp

Synchronous Node.js PGP API backed by Rust rPGP.

Install

npm install node-rpgp

Stability

node-rpgp is stable for the documented synchronous RSA and ECC PGP subset.

Unsupported PGP features fail with stable UNSUPPORTED_FEATURE errors instead of being silently accepted.

Supported v1 Subset

| Feature | Status | | --- | --- | | RSA key generation | Supported for 2048, 3072, and 4096-bit keys | | ECC default profile | Supported: Ed25519 primary key plus X25519 encryption subkey | | curve: "curve25519" | Supported as the Ed25519/X25519 encryption-capable profile | | curve: "ed25519" | Supported as the Ed25519/X25519 encryption-capable profile | | NIST ECC curves | Unsupported, throws UNSUPPORTED_FEATURE | | Passphrase-protected private key generation | Supported for RSA and ECC | | Armored public key parsing | Supported through rPGP | | Armored private key parsing | Supported through rPGP | | Multiple armored private key parsing | Supported by parsing each complete armor block through rPGP | | Armored message parsing | Supported through rPGP | | Public-key encryption | Supported for one RSA or ECC recipient | | Private-key decryption | Supported for one RSA or ECC private key | | Text roundtrip | Supported | | Binary plaintext roundtrip | Supported through armored encrypted messages | | Binary encrypted output | Unsupported, throws UNSUPPORTED_FEATURE |

Unsupported Features

These features currently throw UNSUPPORTED_FEATURE:

• NIST ECC curves: nistP256, nistP384, nistP521
• signing
• signature verification
• password-only message encryption/decryption
• multiple encryption recipients
• multiple decryption keys
• binary encrypted output
• binary message parsing with readMessage({ binaryMessage })

API Overview

const {
  createMessage,
  readMessage,
  readKey,
  readPrivateKey,
  readPrivateKeys,
  decryptKey,
  encrypt,
  decrypt,
  generateKey,
} = require("node-rpgp");

The public API is synchronous and does not expose Sync-suffixed function names.

Generate Keys

const { generateKey, readKey, readPrivateKey } = require("node-rpgp");

const generated = generateKey({
  type: "rsa",
  rsaBits: 2048,
  userIDs: [{ name: "Example User", email: "[email protected]" }],
});

const publicKey = readKey({ armoredKey: generated.publicKey });
const privateKey = readPrivateKey({ armoredKey: generated.privateKey });

Generate the default ECC profile:

const generated = generateKey({
  type: "ecc",
  curve: "curve25519",
  userIDs: [{ name: "Example User", email: "[email protected]" }],
});

curve: "ed25519" currently selects the same Ed25519/X25519 profile. Ed25519 is used for the primary signing/certification key; X25519 is used for the encryption subkey.

Passphrase-Protected Keys

const { generateKey, readPrivateKey, decryptKey } = require("node-rpgp");

const generated = generateKey({ type: "ecc", passphrase: "change me" });
const locked = readPrivateKey({ armoredKey: generated.privateKey });
const unlocked = decryptKey({ privateKey: locked, passphrase: "change me" });

unlocked.decrypted is true.

Passphrase-protected private keys must be unlocked with decryptKey() before decrypt().

Encrypt and Decrypt Text

const { createMessage, decrypt, encrypt, generateKey, readKey, readMessage, readPrivateKey } = require("node-rpgp");

const generated = generateKey();
const publicKey = readKey({ armoredKey: generated.publicKey });
const privateKey = readPrivateKey({ armoredKey: generated.privateKey });

const encrypted = encrypt({
  message: createMessage({ text: "Zażółć gęślą jaźń" }),
  encryptionKeys: publicKey,
});

const decrypted = decrypt({
  message: readMessage({ armoredMessage: encrypted }),
  decryptionKeys: privateKey,
});

console.log(decrypted.data);

Binary Plaintext

const encrypted = encrypt({
  message: createMessage({ binary: new Uint8Array([0, 1, 2, 127, 128, 255]) }),
  encryptionKeys: publicKey,
});

const decrypted = decrypt({
  message: readMessage({ armoredMessage: encrypted }),
  decryptionKeys: privateKey,
  format: "binary",
});

decrypted.data is a Uint8Array.

Errors

Thrown errors use stable code strings where possible:

type NodeRpgpErrorCode =
  | "INVALID_INPUT"
  | "INVALID_PUBLIC_KEY"
  | "INVALID_PRIVATE_KEY"
  | "INVALID_MESSAGE"
  | "INVALID_PASSPHRASE"
  | "DECRYPTION_FAILED"
  | "ENCRYPTION_FAILED"
  | "KEY_GENERATION_FAILED"
  | "UNSUPPORTED_FEATURE";

Security Notes

This package delegates implemented PGP operations to rPGP. It does not implement cryptographic primitives in JavaScript.

The API is synchronous and blocks the event loop. Do not use it with untrusted huge inputs on latency-sensitive request paths without input limits.

No security audit is claimed.

Native Platform Notes

This is a native Node.js package. The release workflow targets Linux x64 glibc and Linux x64 musl artifacts.

License

MIT