# cojson-core-napi

> Node.js N-API bindings for the cojson-core Rust library, providing high-performance.

Latest version **0.20.19** (published 2026-07-03) · MIT license · 0 weekly downloads

## Install

```sh
npm install cojson-core-napi
pnpm add cojson-core-napi
yarn add cojson-core-napi
bun add cojson-core-napi
```

## Health

**Score 55/100 (C)** — status: active.

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

Warnings: low downloads; no esm support; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.20.19 |
| Published | 2026-07-03 |
| First published | 2025-10-08 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >= 12.22.0 < 13 \|\| >= 14.17.0 < 15 \|\| >= 15.12.0 < 16 \|\| >= 16.0.0 |
| Dependencies | 0 |
| Unpacked size | 53.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | anselm_io |
| Keywords | napi-rs, NAPI, N-API, Rust, node-addon, node-addon-api |

## Links

- npm: https://www.npmjs.com/package/cojson-core-napi
- npm.io page: https://npm.io/package/cojson-core-napi

## Recent versions

- 0.20.19 (latest) — 2026-07-03
- 0.20.18 — 2026-04-30
- 0.20.17 — 2026-04-08
- 0.20.16 — 2026-03-31
- 0.20.15 — 2026-03-24
- 0.20.14 — 2026-03-13
- 0.20.12 — 2026-03-02
- 0.20.11 — 2026-02-25
- 0.20.10 — 2026-02-19
- 0.20.9 — 2026-02-09
- 0.20.8 — 2026-02-09
- 0.20.7 — 2026-01-28
- 0.20.6 — 2026-01-26
- 0.20.5 — 2026-01-26
- 0.20.4 — 2026-01-23
- … 43 more at https://npm.io/package/cojson-core-napi/versions

## README

# cojson-core-napi

A high-performance Node.js native addon for cryptographic operations, built with Rust and NAPI. This package provides essential cryptographic primitives for the Jazz framework, including hashing, encryption, digital signatures, and key management.

## Features

- **BLAKE3 Hashing**: Fast, secure cryptographic hashing with incremental support
- **Ed25519 Digital Signatures**: High-performance elliptic curve digital signatures
- **X25519 Key Exchange**: Secure key exchange for encrypted communications
- **XSalsa20 Encryption**: Stream cipher encryption with optional authentication
- **Session Management**: Transaction logging and cryptographic session handling
- **Cross-Platform**: Pre-built binaries for multiple platforms and architectures

## Jazz Framework Integration

This package is a core component of the Jazz framework, providing the cryptographic foundation for:

- **CoJSON**: Collaborative JSON documents with cryptographic integrity
- **Real-time Collaboration**: Secure peer-to-peer synchronization
- **Authentication**: Cryptographic identity and session management
- **End-to-End Encryption**: Secure data transmission and storage

The package is used throughout the Jazz ecosystem by other packages like `cojson`, `jazz-tools`, and various examples in the monorepo.

## Installation

### In the Jazz Monorepo

If you're working within the Jazz monorepo, the package is already available as a workspace dependency:

```bash
# From the monorepo root
pnpm install

# Build the NAPI package specifically
pnpm run build:napi

# Run tests for the NAPI package
pnpm test:napi
```

### As a Standalone Package

```bash
pnpm install cojson-core-napi
```

The package includes pre-built binaries for the following platforms:
- macOS (x64, ARM64)
- Linux (x64, ARM64, ARM, musl)

## API Reference

### Hashing Functions

#### `blake3HashOnce(data: Uint8Array): Uint8Array`

Hash data once using BLAKE3. Returns 32 bytes of hash output.

```typescript
import { blake3HashOnce } from 'cojson-core-napi';

const data = new TextEncoder().encode("Hello, World!");
const hash = blake3HashOnce(data);
console.log(hash.length); // 32
```

#### `blake3HashOnceWithContext(data: Uint8Array, context: Uint8Array): Uint8Array`

Hash data with a context prefix for domain separation.

```typescript
import { blake3HashOnceWithContext } from 'cojson-core-napi';

const data = new TextEncoder().encode("message");
const context = new TextEncoder().encode("domain");
const hash = blake3HashOnceWithContext(data, context);
```

#### `Blake3Hasher`

Incremental hashing for large datasets.

```typescript
import { Blake3Hasher } from 'cojson-core-napi';

const hasher = new Blake3Hasher();
hasher.update(new TextEncoder().encode("part1"));
hasher.update(new TextEncoder().encode("part2"));
const hash = hasher.finalize();
```

### Digital Signatures (Ed25519)

#### `newEd25519SigningKey(): Uint8Array`

Generate a new Ed25519 signing key.

```typescript
import { newEd25519SigningKey, ed25519VerifyingKey, ed25519Sign, ed25519Verify } from 'cojson-core-napi';

const signingKey = newEd25519SigningKey();
const verifyingKey = ed25519VerifyingKey(signingKey);

const message = new TextEncoder().encode("Hello, World!");
const signature = ed25519Sign(signingKey, message);
const isValid = ed25519Verify(verifyingKey, message, signature);
```

#### Key Management Functions

- `ed25519SigningKeyFromBytes(bytes: Uint8Array): Uint8Array` - Validate and copy signing key bytes
- `ed25519VerifyingKeyFromBytes(bytes: Uint8Array): Uint8Array` - Validate and copy verifying key bytes
- `ed25519SignatureFromBytes(bytes: Uint8Array): Uint8Array` - Validate and copy signature bytes
- `ed25519SigningKeyToPublic(signingKey: Uint8Array): Uint8Array` - Derive public key from signing key
- `ed25519SigningKeySign(signingKey: Uint8Array, message: Uint8Array): Uint8Array` - Sign with signing key

### Key Exchange (X25519)

#### `newX25519PrivateKey(): Uint8Array`

Generate a new X25519 private key.

```typescript
import { newX25519PrivateKey, x25519PublicKey, x25519DiffieHellman } from 'cojson-core-napi';

const alicePrivate = newX25519PrivateKey();
const alicePublic = x25519PublicKey(alicePrivate);

const bobPrivate = newX25519PrivateKey();
const bobPublic = x25519PublicKey(bobPrivate);

// Perform key exchange
const aliceShared = x25519DiffieHellman(alicePrivate, bobPublic);
const bobShared = x25519DiffieHellman(bobPrivate, alicePublic);
// aliceShared and bobShared are identical
```

### Encryption Functions

#### `encrypt(value: Uint8Array, keySecret: string, nonceMaterial: Uint8Array): Uint8Array`
#### `decrypt(ciphertext: Uint8Array, keySecret: string, nonceMaterial: Uint8Array): Uint8Array`

Encrypt/decrypt data with a key secret and nonce material.

```typescript
import { encrypt, decrypt } from 'cojson-core-napi';

const keySecret = "keySecret_z11111111111111111111111111111111"; // Base58-encoded key
const nonceMaterial = new TextEncoder().encode("nonce");
const plaintext = new TextEncoder().encode("Secret message");

const ciphertext = encrypt(plaintext, keySecret, nonceMaterial);
const decrypted = decrypt(ciphertext, keySecret, nonceMaterial);
```

#### `encryptXsalsa20(key: Uint8Array, nonceMaterial: Uint8Array, plaintext: Uint8Array): Uint8Array`
#### `decryptXsalsa20(key: Uint8Array, nonceMaterial: Uint8Array, ciphertext: Uint8Array): Uint8Array`

XSalsa20 stream cipher encryption (without authentication).

```typescript
import { encryptXsalsa20, decryptXsalsa20 } from 'cojson-core-napi';

const key = new Uint8Array(32); // 32-byte key
const nonceMaterial = new TextEncoder().encode("nonce");
const plaintext = new TextEncoder().encode("Message");

const ciphertext = encryptXsalsa20(key, nonceMaterial, plaintext);
const decrypted = decryptXsalsa20(key, nonceMaterial, ciphertext);
```

### Sealing/Unsealing (Authenticated Encryption)

#### `seal(message: Uint8Array, senderSecret: string, recipientId: string, nonceMaterial: Uint8Array): Uint8Array`
#### `unseal(sealedMessage: Uint8Array, recipientSecret: string, senderId: string, nonceMaterial: Uint8Array): Uint8Array`

Authenticated encryption with perfect forward secrecy using X25519 + XSalsa20-Poly1305.

```typescript
import { seal, unseal, getSealerId } from 'cojson-core-napi';

const senderSecret = "sealerSecret_z..."; // Base58-encoded private key
const recipientId = "sealer_z..."; // Base58-encoded public key
const nonceMaterial = new TextEncoder().encode("nonce");
const message = new TextEncoder().encode("Secret message");

const sealed = seal(message, senderSecret, recipientId, nonceMaterial);
const unsealed = unseal(sealed, senderSecret, recipientId, nonceMaterial);
```

### Signing/Verification (Base58-wrapped)

#### `sign(message: Uint8Array, secret: Uint8Array): string`
#### `verify(signature: Uint8Array, message: Uint8Array, id: Uint8Array): boolean`

Sign and verify messages with base58-encoded signatures and IDs.

```typescript
import { sign, verify, getSignerId } from 'cojson-core-napi';

const secret = new TextEncoder().encode("signerSecret_z...");
const message = new TextEncoder().encode("Hello, World!");

const signature = sign(message, secret);
const isValid = verify(new TextEncoder().encode(signature), message, new TextEncoder().encode("signer_z..."));
```

### Utility Functions

#### `generateNonce(nonceMaterial: Uint8Array): Uint8Array`

Generate a 24-byte nonce from input material using BLAKE3.

```typescript
import { generateNonce } from 'cojson-core-napi';

const nonceMaterial = new TextEncoder().encode("input");
const nonce = generateNonce(nonceMaterial);
console.log(nonce.length); // 24
```

#### `getSealerId(secret: Uint8Array): string`
#### `getSignerId(secret: Uint8Array): string`

Derive sealer/signer IDs from secrets.

```typescript
import { getSealerId, getSignerId } from 'cojson-core-napi';

const sealerSecret = new TextEncoder().encode("sealerSecret_z...");
const sealerId = getSealerId(sealerSecret);
console.log(sealerId); // "sealer_z..."

const signerSecret = new TextEncoder().encode("signerSecret_z...");
const signerId = getSignerId(signerSecret);
console.log(signerId); // "signer_z..."
```

### Session Management

#### `SessionLog`

Manage cryptographic sessions and transactions.

```typescript
import { SessionLog } from 'cojson-core-napi';

const session = new SessionLog("coId", "sessionId", "signerId");

// Add a new private transaction
const result = session.addNewPrivateTransaction(
  '{"changes": "..."}',
  "signerSecret_z...",
  "keySecret_z...",
  "keyId",
  Date.now(),
  "metadata"
);

// Add a new trusting transaction
const signature = session.addNewTrustingTransaction(
  '{"changes": "..."}',
  "signerSecret_z...",
  Date.now(),
  "metadata"
);

// Decrypt transaction data
const changes = session.decryptNextTransactionChangesJson(0, "keySecret_z...");
const meta = session.decryptNextTransactionMetaJson(0, "keySecret_z...");
```

## Error Handling

All functions throw `Error` objects with descriptive messages for invalid inputs or cryptographic failures.

```typescript
try {
  const hash = blake3HashOnce(invalidData);
} catch (error) {
  console.error('Hashing failed:', error.message);
}
```

## Performance

This package is built with Rust for maximum performance:
- BLAKE3 hashing is significantly faster than SHA-256
- Ed25519 signatures are faster than RSA
- X25519 key exchange is faster than RSA key exchange
- Native code execution avoids JavaScript overhead

## Platform Support

The package includes pre-built binaries for:
- **Windows**: x64, x86, ARM64
- **macOS**: x64, ARM64 (Apple Silicon)
- **Linux**: x64, ARM64, ARM, musl
- **FreeBSD**: x64
- **Android**: ARM64, ARM

## Development

### Within the Jazz Monorepo

```bash
# From the monorepo root - install all dependencies
pnpm install

# Build only the NAPI package
pnpm run build:napi

# Build all packages including NAPI
pnpm run build:packages

# Run tests for the NAPI package
pnpm test:napi

# Run all tests (excluding NAPI tests)
pnpm test

```

### Using in Other Jazz Packages

```typescript
// In any Jazz package, import directly
import { 
  blake3HashOnce, 
  newEd25519SigningKey, 
  encrypt, 
  decrypt 
} from 'cojson-core-napi';

// The package is available as a workspace dependency
// No additional installation needed
```

## License

MIT License - see LICENSE file for details.

## Contributing

Contributions are welcome! Please see the main Jazz repository for contribution guidelines.

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