\n\n[`age-encryption`](https://www.npmjs.com/package/age-encryption) is a TypeScript\nimplementation of the [age](https://age-encryption.org) file encryption format.\n\nIt depends only on the [noble](https://paulmillr.com/noble/) cryptography\nlibraries, and uses the Web Crypto API when available.\n\nIt also provides support for symmetric encryption using passkeys and hardware\nsecurity keys in the browser via WebAuthn, and an interoperable CLI plugin and\nGo library for FIDO2 tokens.\n\n## Installation\n\nThis package is `age-encryption` on npm, and `jsr:@age/age-encryption` on JSR.\n\nIt's compiled for ES2023, and compatible with Node.js 20+, Bun, Deno, and all recent browsers.\n\n```sh\nnpm install age-encryption\n```\n\n```sh\ndeno add jsr:@age/age-encryption\n```\n\n## Usage\n\n`age-encryption` is a modern ES Module with built-in types.\n\n#### Encrypt and decrypt a file with a new recipient / identity pair\n\n```ts\nimport * as age from \"age-encryption\"\n\nconst identity = await age.generateIdentity()\nconst recipient = await age.identityToRecipient(identity)\nconsole.log(identity)\nconsole.log(recipient)\n\nconst e = new age.Encrypter()\ne.addRecipient(recipient)\nconst ciphertext = await e.encrypt(\"Hello, age!\")\n\nconst d = new age.Decrypter()\nd.addIdentity(identity)\nconst out = await d.decrypt(ciphertext, \"text\")\nconsole.log(out)\n```\n\n#### Encrypt and decrypt a file with post-quantum hybrid keys\n\n```ts\nimport * as age from \"age-encryption\"\n\nconst identity = await age.generateHybridIdentity()\nconst recipient = await age.identityToRecipient(identity)\nconsole.log(identity)\nconsole.log(recipient)\n\n// ...\n```\n\n#### ASCII armoring\n\nage encrypted files (the inputs of `Decrypter.decrypt` and outputs of\n`Encrypter.encrypt`) are binary files, of type `Uint8Array`. There is an official ASCII\n\"armor\" format, based on PEM, which provides a way to encode an encrypted file as text.\n\n```ts\nimport * as age from \"age-encryption\"\n\nconst identity = await age.generateIdentity()\nconst recipient = await age.identityToRecipient(identity)\nconsole.log(identity)\nconsole.log(recipient)\n\nconst e = new age.Encrypter()\ne.addRecipient(recipient)\nconst ciphertext = await e.encrypt(\"Hello, age!\")\nconst armored = age.armor.encode(ciphertext)\n\nconsole.log(armored)\n// -----BEGIN AGE ENCRYPTED FILE-----\n// YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSB0QXVkQmNwZ3ZzYnNRZDJP\n// WlFId3hyeFNmRS9SdUVUTkFhY1FXSno5VUFBClNOSWhEbnhoK21TaEs3SWRGdklw\n// OW9pdlBZbDg3SEVSQ1FZZHBvUS90YjgKLS0tIGRCVXNNWmdJS0ZkNlNZbStPZWh4\n// N2FBNUJZdTFxMmYwVTEzUWwvTFVNeUkKrNZnrZjMlXvoCHz0FUS/bp9129XtSV1Q\n// 2twDjjAOwgBtBYoji9gKWgOG4w==\n// -----END AGE ENCRYPTED FILE-----\n\nconst d = new age.Decrypter()\nd.addIdentity(identity)\nconst decoded = age.armor.decode(armored)\nconst out = await d.decrypt(decoded, \"text\")\nconsole.log(out)\n```\n\n#### Encrypt and decrypt a file with a passphrase\n\n```ts\nimport { Encrypter, Decrypter } from \"age-encryption\"\n\nconst e = new Encrypter()\ne.setPassphrase(\"burst-swarm-slender-curve-ability-various-crystal-moon-affair-three\")\nconst ciphertext = await e.encrypt(\"Hello, age!\")\n\nconst d = new Decrypter()\nd.addPassphrase(\"burst-swarm-slender-curve-ability-various-crystal-moon-affair-three\")\nconst out = await d.decrypt(ciphertext, \"text\")\nconsole.log(out)\n```\n\n#### Encrypt and decrypt using the Streams API\n\nYou can also encrypt and decrypt [ReadableStreams][]. This can be useful for\nencrypting or decrypting large files, requests, or responses on the fly.\n\n[ReadableStreams]: https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream\n\n```ts\nimport { Encrypter, Decrypter } from \"age-encryption\"\n\nconst file = new File([new TextEncoder().encode(\"age\")], \"age.txt\")\n\nconst e = new Encrypter()\ne.setScryptWorkFactor(12)\ne.setPassphrase(\"light-original-energy-average-wish-blind-vendor-pencil-illness-scorpion\")\nconst encryptedStream = await e.encrypt(file.stream())\nconsole.log(encryptedStream.size(file.size))\n\nconst d = new Decrypter()\nd.addPassphrase(\"light-original-energy-average-wish-blind-vendor-pencil-illness-scorpion\")\nconst decryptedStream = await d.decrypt(encryptedStream)\nconsole.log(decryptedStream.size(encryptedStream.size(file.size)))\n\nconsole.log(await new Response(decryptedStream).text())\n```\n\n### Browser usage\n\n`age-encryption` is compatible with modern bundlers such as [esbuild](https://esbuild.github.io/).\n\nTo produce a classic library file that sets `age` as a global variable, you can run\n\n```sh\ncd \"$(mktemp -d)\" && npm init -y && npm install esbuild age-encryption\nnpx esbuild --target=es2022 --bundle --minify --outfile=age.js --global-name=age age-encryption\n```\n\nor download a pre-built one from the [Releases page](https://github.com/FiloSottile/typage/releases).\n\n\n\nThen, you can use it like this\n\n```html\n\n\n```\n\n#### Encrypt and decrypt a file with a passkey\n\nIn the browser, `age-encryption` supports *symmetric* encryption with passkeys,\ndiscoverable credentials that can be stored and synced by platforms (e.g. iCloud\nKeychain) or password managers (e.g. 1Password).\n\nThis functionality uses the WebAuthn PRF extension, which is supported by recent\nbrowsers and authenticators. When encrypting or decrypting a file, the user will\nbe prompted to select a passkey associated with the replying party ID (usually\nthe website origin). Passkeys not generated by `createCredential` can be used if\nthey have the `prf` extension enabled. The identity string returned by\n`createCredential` can be optionally provided at encryption/decryption time to\nprevent the user from selecting other passkeys.\n\n```ts\nawait age.webauthn.createCredential({ keyName: \"age encryption key 🦈\" })\n\nconst e = new age.Encrypter()\ne.addRecipient(new age.webauthn.WebAuthnRecipient())\nconst ciphertext = await e.encrypt(\"Hello, age!\")\nconst armored = age.armor.encode(ciphertext)\nconsole.log(armored)\n\nconst d = new age.Decrypter()\nd.addIdentity(new age.webauthn.WebAuthnIdentity())\nconst decoded = age.armor.decode(armored)\nconst out = await d.decrypt(decoded, \"text\")\nconsole.log(out)\n```\n\nEach encryption and decryption operation requires the authenticator and user\nconfirmation, there is no extractable key, and encrypted files can't be linked\nto an identity or to each other without the ability to decrypt them.\n\n#### Encrypt and decrypt a file with a security key\n\n`age-encryption` also supports non-discoverable FIDO2 credentials, usually\nuseful to encrypt files with hardware security keys (e.g. YubiKeys).\n\nEncryption and decryption work the same as with passkeys, but the identity\nstring is mandatory, because these credentials are not discoverable.\n\n```ts\nconst identity = await age.webauthn.createCredential({\n type: \"security-key\", keyName: \"age encryption key\" })\nconsole.log(identity) // AGE-PLUGIN-FIDO2PRF-1...\n\nconst e = new age.Encrypter()\ne.addRecipient(new age.webauthn.WebAuthnRecipient({ identity: identity }))\nconst ciphertext = await e.encrypt(\"Hello, age!\")\nconst armored = age.armor.encode(ciphertext)\nconsole.log(armored)\n\nconst d = new age.Decrypter()\nd.addIdentity(new age.webauthn.WebAuthnIdentity({ identity: identity }))\nconst decoded = age.armor.decode(armored)\nconst out = await d.decrypt(decoded, \"text\")\nconsole.log(out)\n```\n\n##### age-plugin-fido2prf\n\nIf a credential is associated with a USB FIDO2 security key (e.g. a YubiKey),\nits identity string can be used outside the browser with the provided\n`age-plugin-fido2prf` plugin.\n\nFiles encrypted in the browser will decrypt from the CLI, and vice-versa. Since\nWebAuthn encryption is symmetric, there is no recipient encoding, only\nidentities. To encrypt to an identity, use `age -e -i`.\n\n```sh\ngo install filippo.io/typage/fido2prf/cmd/age-plugin-fido2prf@latest\n\ncat << EOF > identity.txt\nAGE-PLUGIN-FIDO2PRF-1Q9VGPY2E7S5FJJS3N7P03TZMMEJ94S6HYLDJLU8WVX2HP8SXQUGJUZ68LN6GP705662VS06UEX5J42W80NZT8Y2DQ8GTDN50VGATCNYLJ4HY2W5J67KYCTM858UFDCNUUDZ6U28WEMUKGVG9RNELRJDH8NFEP999Z8XFSS8XLS448A3TSQKWG9DMPL8ZCRRA02KSUC2UXTYDFNVYAE5KCMMRV9KXSMMNWJQKXATNVGTXV35G\nEOF\n\nage -d -i identity.txt << EOF\n-----BEGIN AGE ENCRYPTED FILE-----\nYWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IGFnZS1lbmNyeXB0aW9uLm9yZy9maWRv\nMnByZiBJSFFHd0poUkNSYThuVnB6b1R1bjdBClJ3d3dRUUtiRjN4TkU0VWx1SUZU\nWnJtTVBFUTZoR0d4eUx2WXFOSFBsQzQKLS0tIFNWVGRnNzV4L00wblRENUZyYlFh\nWU5wQmVsdG5hL0lmcXhTVzZHTVRtdFkK2rYiueXr8dgM1GiLVrBMC/LQRzkDacMw\nGEtVcMZyh7b90z6VR3KT92EIlA==\n-----END AGE ENCRYPTED FILE-----\nEOF\n```\n\nCredentials can be generated from the command line with `age-plugin-fido2prf\n-generate RPID`. Note that they will be usable inside the browser only if the\nrelying party ID matches the website's origin.\n\nAll the features of the plugin are also available as a Go library at\n[filippo.io/typage/fido2prf](https://pkg.go.dev/filippo.io/typage/fido2prf).\n\n#### Web Crypto identities\n\nYou can use a CryptoKey as an identity. It must have an `algorithm` of `X25519`,\nand support the `deriveBits` key usage. It doesn't need to be extractable.\n\n```ts\nconst keyPair = await crypto.subtle.generateKey({ name: \"X25519\" }, false, [\"deriveBits\"])\nconst identity = (keyPair as CryptoKeyPair).privateKey\nconst recipient = await age.identityToRecipient(identity)\nconsole.log(recipient)\n\nconst e = new age.Encrypter()\ne.addRecipient(recipient)\nconst file = await e.encrypt(\"age\")\n\nconst d = new age.Decrypter()\nd.addIdentity(identity)\nconst out = await d.decrypt(file, \"text\")\nconsole.log(out)\n```\n\n### Custom recipients and identities\n\nYou can implement the `Recipient` and `Identity` interfaces to use custom types\nas recipients and identities.\n\nThis lets you use use remote APIs and secrets managers to wrap files keys, and\ninteroperate with [age plugins](https://github.com/FiloSottile/awesome-age?tab=readme-ov-file#plugins).\n","readmeFilename":"README.md"}
![\"The](\"https://github.com/FiloSottile/age/blob/main/logo/logo.svg\"){kind=logo}
\n