diff --git a/packages/core/src/lib/waku_message/version_0.ts b/packages/core/src/lib/waku_message/version_0.ts index 2073019cbe..b58251f7d5 100644 --- a/packages/core/src/lib/waku_message/version_0.ts +++ b/packages/core/src/lib/waku_message/version_0.ts @@ -92,6 +92,18 @@ export class Encoder implements IEncoder { } } +/** + * Creates an encoder that encode messages without Waku level encryption or signature. + * + * An encoder is used to encode messages in the [`14/WAKU2-MESSAGE](https://rfc.vac.dev/spec/14/) + * format to be sent over the Waku network. The resulting encoder can then be + * pass to { @link @waku/interfaces.LightPush.push } or + * { @link @waku/interfaces.Relay.send } to automatically encode outgoing + * messages. + * + * @param contentTopic The content topic to set on outgoing messages. + * @param ephemeral An optional flag to mark message as ephemeral, ie, not to be stored by Waku Store nodes. + */ export function createEncoder( contentTopic: string, ephemeral = false @@ -135,6 +147,17 @@ export class Decoder implements IDecoder { } } +/** + * Creates an decoder that decode messages without Waku level encryption. + * + * A decoder is used to decode messages from the [14/WAKU2-MESSAGE](https://rfc.vac.dev/spec/14/) + * format when received from the Waku network. The resulting decoder can then be + * pass to { @link @waku/interfaces.Filter.subscribe } or + * { @link @waku/interfaces.Relay.subscribe } to automatically decode incoming + * messages. + * + * @param contentTopic The resulting decoder will only decode messages with this content topic. + */ export function createDecoder(contentTopic: string): Decoder { return new Decoder(contentTopic); } diff --git a/packages/message-encryption/src/ecies.ts b/packages/message-encryption/src/ecies.ts index 9fe01bd235..6b73c5f38c 100644 --- a/packages/message-encryption/src/ecies.ts +++ b/packages/message-encryption/src/ecies.ts @@ -65,6 +65,24 @@ class Encoder implements IEncoder { } } +/** + * Creates an encoder that encrypts messages using ECIES for the given public, + * as defined in [26/WAKU2-PAYLOAD](https://rfc.vac.dev/spec/26/). + * + * An encoder is used to encode messages in the [`14/WAKU2-MESSAGE](https://rfc.vac.dev/spec/14/) + * format to be sent over the Waku network. The resulting encoder can then be + * pass to { @link @waku/interfaces.LightPush.push } or + * { @link @waku/interfaces.Relay.send } to automatically encrypt + * and encode outgoing messages. + * + * The payload can optionally be signed with the given private key as defined + * in [26/WAKU2-PAYLOAD](https://rfc.vac.dev/spec/26/). + * + * @param contentTopic The content topic to set on outgoing messages. + * @param publicKey The public key to encrypt the payload for. + * @param sigPrivKey An optional private key to used to sign the payload before encryption. + * @param ephemeral An optional flag to mark message as ephemeral, ie, not to be stored by Waku Store nodes. + */ export function createEncoder( contentTopic: string, publicKey: Uint8Array, @@ -132,6 +150,19 @@ class Decoder extends DecoderV0 implements IDecoder { } } +/** + * Creates a decoder that decrypts messages using ECIES, using the given private + * key as defined in [26/WAKU2-PAYLOAD](https://rfc.vac.dev/spec/26/). + * + * A decoder is used to decode messages from the [14/WAKU2-MESSAGE](https://rfc.vac.dev/spec/14/) + * format when received from the Waku network. The resulting decoder can then be + * pass to { @link @waku/interfaces.Filter.subscribe } or + * { @link @waku/interfaces.Relay.subscribe } to automatically decrypt and + * decode incoming messages. + * + * @param contentTopic The resulting decoder will only decode messages with this content topic. + * @param privateKey The private key used to decrypt the message. + */ export function createDecoder( contentTopic: string, privateKey: Uint8Array diff --git a/packages/message-encryption/src/index.ts b/packages/message-encryption/src/index.ts index d10b2ab004..7705df57c3 100644 --- a/packages/message-encryption/src/index.ts +++ b/packages/message-encryption/src/index.ts @@ -14,6 +14,9 @@ export const OneMillion = BigInt(1_000_000); export { generatePrivateKey, generateSymmetricKey, getPublicKey }; +export * as ecies from "./ecies.js"; +export * as symmetric from "./symmetric.js"; + export const Version = 1; export type Signature = { diff --git a/packages/message-encryption/src/symmetric.ts b/packages/message-encryption/src/symmetric.ts index b3e09f7a66..794cf47f4f 100644 --- a/packages/message-encryption/src/symmetric.ts +++ b/packages/message-encryption/src/symmetric.ts @@ -63,6 +63,24 @@ class Encoder implements IEncoder { } } +/** + * Creates an encoder that encrypts messages using symmetric encryption for the + * given key, as defined in [26/WAKU2-PAYLOAD](https://rfc.vac.dev/spec/26/). + * + * An encoder is used to encode messages in the [`14/WAKU2-MESSAGE](https://rfc.vac.dev/spec/14/) + * format to be sent over the Waku network. The resulting encoder can then be + * pass to { @link @waku/interfaces.LightPush.push } or + * { @link @waku/interfaces.Relay.send } to automatically encrypt + * and encode outgoing messages. + * + * The payload can optionally be signed with the given private key as defined + * in [26/WAKU2-PAYLOAD](https://rfc.vac.dev/spec/26/). + * + * @param contentTopic The content topic to set on outgoing messages. + * @param symKey The symmetric key to encrypt the payload with. + * @param sigPrivKey An optional private key to used to sign the payload before encryption. + * @param ephemeral An optional flag to mark message as ephemeral, ie, not to be stored by Waku Store nodes. + */ export function createEncoder( contentTopic: string, symKey: Uint8Array, @@ -130,6 +148,19 @@ class Decoder extends DecoderV0 implements IDecoder { } } +/** + * Creates a decoder that decrypts messages using symmetric encryption, using + * the given key as defined in [26/WAKU2-PAYLOAD](https://rfc.vac.dev/spec/26/). + * + * A decoder is used to decode messages from the [14/WAKU2-MESSAGE](https://rfc.vac.dev/spec/14/) + * format when received from the Waku network. The resulting decoder can then be + * pass to { @link @waku/interfaces.Filter.subscribe } or + * { @link @waku/interfaces.Relay.subscribe } to automatically decrypt and + * decode incoming messages. + * + * @param contentTopic The resulting decoder will only decode messages with this content topic. + * @param symKey The symmetric key used to decrypt the message. + */ export function createDecoder( contentTopic: string, symKey: Uint8Array