Add TypeDoc docs

.eslintrc.cjs

@@ -9,7 +9,7 @@ module.exports = {
         'plugin:@typescript-eslint/strict-type-checked',
         'plugin:@typescript-eslint/stylistic-type-checked',
     ],
-    plugins: ['@typescript-eslint', '@stylistic'],
+    plugins: ['@typescript-eslint', '@stylistic', 'tsdoc'],
     parser: '@typescript-eslint/parser',
     parserOptions: {
         project: true,
@@ -29,5 +29,7 @@ module.exports = {
 
         'no-constant-binary-expression': "error",
         'no-self-compare': "error",
+
+        'tsdoc/syntax': "error",
     },
 };

README.md

@@ -22,6 +22,8 @@ npm install age-encryption
 
 `age-encryption` is a modern ES Module, compatible with Node.js and Bun, with built-in types.
 
+The whole API is [documented with TypeDoc](docs/README.md).
+
 #### Encrypt and decrypt a file with a new recipient / identity pair
 
 ```ts
@@ -121,3 +123,11 @@ d.addIdentity(identity)
 const out = await d.decrypt(file, "text")
 console.log(out)
 ```
+
+### Custom recipients and identities
+
+You can implement the `Recipient` and `Identity` interfaces to use custom types
+as recipients and identities.
+
+This lets you use use remote APIs and secrets managers to wrap files keys, and
+interoperate with [age plugins](https://github.com/FiloSottile/awesome-age?tab=readme-ov-file#plugins).

docs/README.md

@@ -0,0 +1,21 @@
+**age-encryption**
+
+***
+
+# age-encryption
+
+## Classes
+
+- [Decrypter](classes/Decrypter.md)
+- [Encrypter](classes/Encrypter.md)
+- [Stanza](classes/Stanza.md)
+
+## Interfaces
+
+- [Identity](interfaces/Identity.md)
+- [Recipient](interfaces/Recipient.md)
+
+## Functions
+
+- [generateIdentity](functions/generateIdentity.md)
+- [identityToRecipient](functions/identityToRecipient.md)

docs/classes/Decrypter.md

@@ -0,0 +1,152 @@
+[**age-encryption**](../README.md)
+
+***
+
+[age-encryption](../README.md) / Decrypter
+
+# Class: Decrypter
+
+Defined in: [index.ts:179](https://github.com/FiloSottile/typage/blob/71f68da909e30220d568bfb648bafe630e17f03c/lib/index.ts#L179)
+
+Decrypts a file using the given identities.
+
+First, call [Decrypter.addPassphrase](Decrypter.md#addpassphrase) to set a passphrase for symmetric
+decryption, and/or [Decrypter.addIdentity](Decrypter.md#addidentity) to specify one or more
+identities. All passphrases and/or identities are tried in parallel for each
+file. Then, call [Decrypter.decrypt](Decrypter.md#decrypt) one or more times to decrypt files
+using the configured passphrase and/or identities.
+
+## Constructors
+
+### new Decrypter()
+
+> **new Decrypter**(): [`Decrypter`](Decrypter.md)
+
+#### Returns
+
+[`Decrypter`](Decrypter.md)
+
+## Methods
+
+### addIdentity()
+
+> **addIdentity**(`s`): `void`
+
+Defined in: [index.ts:213](https://github.com/FiloSottile/typage/blob/71f68da909e30220d568bfb648bafe630e17f03c/lib/index.ts#L213)
+
+Add an identity to decrypt file(s) with. This method can be called
+multiple times to try multiple identities.
+
+#### Parameters
+
+##### s
+
+The identity to decrypt the file with. Either a string
+beginning with `AGE-SECRET-KEY-1...`, an X25519 private
+[CryptoKey](https://developer.mozilla.org/en-US/docs/Web/API/CryptoKey)
+object, or an object implementing the [Identity](../interfaces/Identity.md) interface.
+
+A CryptoKey object must have
+[type](https://developer.mozilla.org/en-US/docs/Web/API/CryptoKey/type)
+`private`,
+[algorithm](https://developer.mozilla.org/en-US/docs/Web/API/CryptoKey/algorithm)
+`{name: 'X25519'}`, and
+[usages](https://developer.mozilla.org/en-US/docs/Web/API/CryptoKey/usages)
+`["deriveBits"]`. For example:
+```js
+const keyPair = await crypto.subtle.generateKey({ name: "X25519" }, false, ["deriveBits"])
+decrypter.addIdentity(key.privateKey)
+```
+
+`string` | `CryptoKey` | [`Identity`](../interfaces/Identity.md)
+
+#### Returns
+
+`void`
+
+***
+
+### addPassphrase()
+
+> **addPassphrase**(`s`): `void`
+
+Defined in: [index.ts:188](https://github.com/FiloSottile/typage/blob/71f68da909e30220d568bfb648bafe630e17f03c/lib/index.ts#L188)
+
+Add a passphrase to decrypt password-encrypted file(s) with. This method
+can be called multiple times to try multiple passphrases.
+
+#### Parameters
+
+##### s
+
+`string`
+
+The passphrase to decrypt the file with.
+
+#### Returns
+
+`void`
+
+***
+
+### decrypt()
+
+#### Call Signature
+
+> **decrypt**(`file`, `outputFormat`?): `Promise`\<`Uint8Array`\>
+
+Defined in: [index.ts:231](https://github.com/FiloSottile/typage/blob/71f68da909e30220d568bfb648bafe630e17f03c/lib/index.ts#L231)
+
+Decrypt a file using the configured passphrases and/or identities.
+
+##### Parameters
+
+###### file
+
+`Uint8Array`
+
+The file to decrypt.
+
+###### outputFormat?
+
+`"uint8array"`
+
+The format to return the decrypted file in. If
+`"text"` is passed, the file's plaintext will be decoded as UTF-8 and
+returned as a string. Optional. It defaults to `"uint8array"`.
+
+##### Returns
+
+`Promise`\<`Uint8Array`\>
+
+A promise that resolves to the decrypted file.
+
+#### Call Signature
+
+> **decrypt**(`file`, `outputFormat`): `Promise`\<`string`\>
+
+Defined in: [index.ts:232](https://github.com/FiloSottile/typage/blob/71f68da909e30220d568bfb648bafe630e17f03c/lib/index.ts#L232)
+
+Decrypt a file using the configured passphrases and/or identities.
+
+##### Parameters
+
+###### file
+
+`Uint8Array`
+
+The file to decrypt.
+
+###### outputFormat
+
+`"text"`
+
+The format to return the decrypted file in. If
+`"text"` is passed, the file's plaintext will be decoded as UTF-8 and
+returned as a string. Optional. It defaults to `"uint8array"`.
+
+##### Returns
+
+`Promise`\<`string`\>
+
+A promise that resolves to the decrypted file.

docs/classes/Encrypter.md

@@ -0,0 +1,129 @@
+[**age-encryption**](../README.md)
+
+***
+
+[age-encryption](../README.md) / Encrypter
+
+# Class: Encrypter
+
+Defined in: [index.ts:72](https://github.com/FiloSottile/typage/blob/71f68da909e30220d568bfb648bafe630e17f03c/lib/index.ts#L72)
+
+Encrypts a file using the given passphrase or recipients.
+
+First, call [Encrypter.setPassphrase](Encrypter.md#setpassphrase) to set a passphrase for symmetric
+encryption, or [Encrypter.addRecipient](Encrypter.md#addrecipient) to specify one or more
+recipients. Then, call [Encrypter.encrypt](Encrypter.md#encrypt) one or more times to encrypt
+files using the configured passphrase or recipients.
+
+## Constructors
+
+### new Encrypter()
+
+> **new Encrypter**(): [`Encrypter`](Encrypter.md)
+
+#### Returns
+
+[`Encrypter`](Encrypter.md)
+
+## Methods
+
+### addRecipient()
+
+> **addRecipient**(`s`): `void`
+
+Defined in: [index.ts:118](https://github.com/FiloSottile/typage/blob/71f68da909e30220d568bfb648bafe630e17f03c/lib/index.ts#L118)
+
+Add a recipient to encrypt the file(s) for. This method can be called
+multiple times to encrypt the file(s) for multiple recipients.
+
+#### Parameters
+
+##### s
+
+The recipient to encrypt the file for. Either a string
+beginning with `age1...` or an object implementing the [Recipient](../interfaces/Recipient.md)
+interface.
+
+`string` | [`Recipient`](../interfaces/Recipient.md)
+
+#### Returns
+
+`void`
+
+***
+
+### encrypt()
+
+> **encrypt**(`file`): `Promise`\<`Uint8Array`\>
+
+Defined in: [index.ts:138](https://github.com/FiloSottile/typage/blob/71f68da909e30220d568bfb648bafe630e17f03c/lib/index.ts#L138)
+
+Encrypt a file using the configured passphrase or recipients.
+
+#### Parameters
+
+##### file
+
+The file to encrypt. If a string is passed, it will be
+encoded as UTF-8.
+
+`string` | `Uint8Array`
+
+#### Returns
+
+`Promise`\<`Uint8Array`\>
+
+A promise that resolves to the encrypted file as a Uint8Array.
+
+***
+
+### setPassphrase()
+
+> **setPassphrase**(`s`): `void`
+
+Defined in: [index.ts:89](https://github.com/FiloSottile/typage/blob/71f68da909e30220d568bfb648bafe630e17f03c/lib/index.ts#L89)
+
+Set the passphrase to encrypt the file(s) with. This method can only be
+called once, and can't be called if [Encrypter.addRecipient](Encrypter.md#addrecipient) has
+been called.
+
+The passphrase is passed through the scrypt key derivation function, but
+it needs to have enough entropy to resist offline brute-force attacks.
+You should use at least 8-10 random alphanumeric characters, or 4-5
+random words from a list of at least 2000 words.
+
+#### Parameters
+
+##### s
+
+`string`
+
+The passphrase to encrypt the file with.
+
+#### Returns
+
+`void`
+
+***
+
+### setScryptWorkFactor()
+
+> **setScryptWorkFactor**(`logN`): `void`
+
+Defined in: [index.ts:106](https://github.com/FiloSottile/typage/blob/71f68da909e30220d568bfb648bafe630e17f03c/lib/index.ts#L106)
+
+Set the scrypt work factor to use when encrypting the file(s) with a
+passphrase. The default is 18. Using a lower value will require stronger
+passphrases to resist offline brute-force attacks.
+
+#### Parameters
+
+##### logN
+
+`number`
+
+The base-2 logarithm of the scrypt work factor.
+
+#### Returns
+
+`void`