# noise-handshake

> Noise protocol handshake

Latest version **4.2.0** (published 2025-12-01) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install noise-handshake
pnpm add noise-handshake
yarn add noise-handshake
bun add noise-handshake
```

## Health

**Score 53/100 (C)** — status: stable.

Positive: has types package; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 4.2.0 |
| Published | 2025-12-01 |
| First published | 2021-07-09 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | separate (@types/noise-handshake) |
| Module format | CommonJS |
| Dependencies | 3 |
| Unpacked size | 29 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 20 |
| Author | Holepunch |
| Maintainers | mafintosh, chm-diederichs |

## Links

- npm: https://www.npmjs.com/package/noise-handshake
- Repository: https://github.com/holepunchto/noise-handshake
- Homepage: https://github.com/holepunchto/noise-handshake#readme
- Issues: https://github.com/holepunchto/noise-handshake/issues
- npm.io page: https://npm.io/package/noise-handshake

## Dependencies (3)

- [b4a](https://npm.io/package/b4a.md) ^1.1.0
- [nanoassert](https://npm.io/package/nanoassert.md) ^2.0.0
- [sodium-universal](https://npm.io/package/sodium-universal.md) ^5.0.0

## Recent versions

- 4.2.0 (latest) — 2025-12-01
- 4.1.0 — 2025-04-12
- 4.0.2 — 2024-09-19
- 4.0.1 — 2024-09-19
- 4.0.0 — 2024-01-23
- 3.1.0 — 2024-01-23
- 3.0.3 — 2023-05-31
- 3.0.2 — 2023-01-10
- 3.0.1 — 2022-12-13
- 3.0.0 — 2022-09-21
- 2.2.0 — 2021-11-23
- 2.1.2 — 2021-11-23
- 2.1.1 — 2021-11-23
- 2.1.0 — 2021-09-16
- 2.0.0 — 2021-09-08
- … 5 more at https://npm.io/package/noise-handshake/versions

## README

# noise-handshake

## Usage
```js
const Noise = require('noise-handshake')
const Cipher = require('noise-handshake/cipher')
const initiator = new Noise('IK', true)
const responder = new Noise('IK', false)

const prologue = Buffer.alloc(0)

// preshared key
initiator.initialise(prologue, responder.s.publicKey)
responder.initialise(prologue)

// -> e, es, s, ss
const message = initiator.send()
responder.recv(message)

// <- e, ee, se
const reply = responder.send()
initiator.recv(reply)

console.log(initiator.complete) // true

// convention is to use rx for
// sending and tx for receiving

// initiator.rx === responder.tx
// responder.rx === initiator.tx

// instantiate a cipher using shared secrets
const send = new Cipher(initiator.tx)
const recieve = new Cipher(responder.rx)

const msg = Buffer.from('hello, world')

const enc = send.encrypt(msg)
console.log(recieve.decrypt(enc)) // hello, world
```

## API

#### `const peer = new Noise(pattern, initiator, staticKeypair, [opts])`

Create a new handshake state for a given pattern. Initiator should be either `true` or `false` depending on the role. A preexisting keypair may be passed as `staticKeypair`

`opts` may be used to pass in the following:
- `curve`: module for performing Noise over other curves.
- `psk`: a 32-byte buffer containing a pre-shared key for patterns containing `psk0`. (Other psk positions are not currently supported.)

Curve modules should export the following:
```
{
  DHLEN,
  PKLEN,
  SKLEN,
  ALG,
  generateKeyPair,
  dh
}
```

See [dh.js](./dh) for an example.

#### `peer.initialise(prologue, remoteStatic)`

Initialise the handshake state with a prologue and any preshared keys.

#### `const buf = send([payload])`

Send the next message in the handshake, add an optional payload buffer to be included in the message, payload is a zero length buffer by default.

#### `const payload = peer.recv(buf)`

Receive a handshake message from the peer and return the encrypted payload.

#### `peer.complete`

`true` or `false`. Indicates whether `rx` and `tx` have been created yet.

When complete, the working handshake state shall be cleared *only* the following state shall remain on the object:

```js
{
  tx, // session key to decrypt messages from remote peer
  rx, // session key to encrypt messages to remote peer
  rs, // the remote peer's public key,
  hash, // a hash of the entire handshake state
}
```

## License

Apache-2.0

---
_Source: https://npm.io/package/noise-handshake · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._