age-encryption is a TypeScript implementation of the age file encryption format.

All low-level cryptographic operations are implemented with libsodium.js.

Installation

npm install age-encryption

Usage

age-encryption is a modern ES Module, compatible with Node.js and Bun, with built-in types.

There is a single exported function, age(), which returns a Promise that resolves to an object that provides the package API. This is necessary to ensure that applications always call sodium.ready() from libsodium.js.

Encrypt and decrypt a file with a new recipient / identity pair

import age from "age-encryption"

// Initialize the age library (calls sodium.ready).
const { Encrypter, Decrypter, generateIdentity, identityToRecipient } = await age()

const identity = generateIdentity()
const recipient = identityToRecipient(identity)
console.log(identity)
console.log(recipient)

const e = new Encrypter()
e.addRecipient(recipient)
const ciphertext = e.encrypt("Hello, age!")

const d = new Decrypter()
d.addIdentity(identity)
const out = d.decrypt(ciphertext, "text")
console.log(out)

Encrypt and decrypt a file with a passphrase

import age from "age-encryption"

// Initialize the age library (calls sodium.ready).
const { Encrypter, Decrypter } = await age()

const e = new Encrypter()
e.setPassphrase("burst-swarm-slender-curve-ability-various-crystal-moon-affair-three")
const ciphertext = e.encrypt("Hello, age!")

const d = new Decrypter()
d.addPassphrase("burst-swarm-slender-curve-ability-various-crystal-moon-affair-three")
const out = d.decrypt(ciphertext, "text")
console.log(out)

Browser usage

age-encryption is compatible with modern bundlers such as esbuild.

To produce a classic library file that sets age() as a global variable, you can run

cd "$(mktemp)" && npm init -y && npm install esbuild age-encryption
echo 'import age from "age-encryption"; globalThis.age = age' | \
  npx esbuild --target=es6 --bundle --minify --outfile=age.js

Then, you can use it like this

<script src="age.js"></script>
<script>
    age().then((age) => {
        const identity = age.generateIdentity()
        const recipient = age.identityToRecipient(identity)
        console.log(identity)
        console.log(recipient)

        const e = new age.Encrypter()
        e.addRecipient(recipient)
        const ciphertext = e.encrypt("Hello, age!")

        const d = new age.Decrypter()
        d.addIdentity(identity)
        const out = d.decrypt(ciphertext, "text")
        console.log(out)
    })
</script>

(Or, in a script with type="module", you can use the top-level await syntax like in the examples above.)