zig-crypto

Zero-allocation N-API native extension for high-performance ID generation, encoding, and encrypted tokens. Written in Zig — prebuilt binaries for Linux (x64/ARM64), macOS (x64/ARM64), Windows (x64). No node-gyp or compilation.

npm install zig-crypto

Quick Start

import { nanoid, Snowflake, codec, zst } from "zig-crypto";

nanoid(); // "V1StGXR8_Z5jdHi6B-myT"
nanoid(10); // "IRFa-VaY2b"
nanoid.Batch(1000, 21); // string[1000] — one JS↔native crossing

Snowflake.Id(); // 1577836800000000001n (BigInt)
extractSnowflakeTime(id); // Date.now()

codec.base64.encode(Buffer.from("hello")); // "aGVsbG8="
codec.base58.encode(Buffer.from("hello")); // "Cn8eVd3"
codec.hex.encode(Buffer.from("hello")); // "68656c6c6f"

// ZST: XChaCha20-Poly1305 + BLAKE2b KDF encrypted tokens
const key = zst.generateKey(32);
const token = zst.sign({ sub: "user_123" }, key, {
  expiresIn: "1h",
  audience: "api.example.com",
});
const claims = zst.verify(token, key, { audience: "api.example.com" });
const header = zst.decode(token); // no crypto, header only

API

nanoid

| Method | Returns | Description | | ----------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | nanoid(length?) | string | Crypto random ID, 64-char URL-safe alphabet. Length 1–128 (default 21). Zero modulo bias (byte & 0x3F), zero branching, no rejection sampling. | | Batch(count, length?) | string[] | Generate IDs in a single native call. Count 1–1000. No Buffer.toString() — creates V8 strings directly. | | BatchBuffer(count, length?) | Buffer | Zero-copy batch — all IDs concatenated in one Buffer. |

Snowflake

64-bit distributed IDs: 41-bit timestamp (EPOCH=2026-01-01) + 10-bit node ID (auto-derived from hostname hash) + 12-bit sequence (mutex-protected).

| Method | Returns | Description | | -------------- | ---------- | ---------------------- | | Id() | bigint | One snowflake ID | | Batch(count) | bigint[] | Multiple IDs, one call |

Extractors: extractSnowflakeTime(id) → number, extractSnowflakeNodeId(id) → number, extractSnowflakeSequence(id) → number.

codec

| Module | Methods | Options | | -------- | ---------------------------------------------- | -------------------------------------------- | | base64 | encode, encodeBuf, decode, decodeConst | { urlSafe?: boolean } — ±/ vs -_ alphabet | | base58 | encode, decode | — | | hex | encode, decode | { upper?: boolean } — uppercase hex |

decodeConst is constant-time (timing-safe). All implemented in Zig with SIMD where applicable.

zst — Zig Secure Tokens

Sign (encrypt) a payload:

zst.sign(payload, key, options?): string

| Param | Type | Notes | | --------- | -------------------------------- | ----------------- | | payload | object \| string \| Buffer | JSON-serializable | | key | string \| Buffer \| Uint8Array | Must be ≥32 bytes | | options | ZstSignOptions | See below |

ZstSignOptions:

| Option | Type | Description | | --------------- | --------------------- | --------------------------------------------- | | expiresIn | number \| string | e.g. 3600, "1h", "7d" | | notBefore | string | e.g. "5m" | | audience | string | Claim aud | | issuer | string | Claim iss | | subject | string | Claim sub | | jwtid | string | Claim jti (explicit) | | rev | number | Revocation counter — O(1) "logout everywhere" | | header | Record<string, any> | Custom header fields | | mutatePayload | boolean | Inject iat/exp into payload |

Verify (decrypt) a token:

zst.verify(token, key, options?): ZstPayload

ZstVerifyOptions:

| Option | Type | Description | | ------------------ | ------------------ | ---------------------------------- | | audience | string | Reject if aud mismatch | | issuer | string | Reject if iss mismatch | | subject | string | Reject if sub mismatch | | jwtid | string | Reject if jti mismatch | | currentRev | number | Reject if token rev ≠ this value | | clockTolerance | number | Leeway (seconds) for exp/nbf | | clockTimestamp | number | Fixed time for testing | | maxAge | number \| string | Reject tokens older than this | | ignoreExpiration | boolean | Skip exp check | | ignoreNotBefore | boolean | Skip nbf check |

Decode (header only, no crypto):

zst.decode(token): ZstDecodedHeader
// → { ver: "1", typ: "ZST", mode: "local", encrypted: true }

Generate key:

zst.generateKey(length?): Buffer
// length default 32, minimum 32

Error hierarchy:

ZstError
├── ZstExpiredError     // token exp passed
├── ZstNotBeforeError   // used before nbf
├── ZstAudienceError    // aud mismatch
├── ZstIssuerError      // iss mismatch
├── ZstSubjectError     // sub mismatch
├── ZstJwtIdError       // jti mismatch
└── ZstRevokedError     // rev counter mismatch

Token format:

zst_v1.local.<header_b64>.<nonce_b64>.<ciphertext_b64>.<tag_b64>

| Part | Contents | | ---------------- | ---------------------------------------------------- | | header_b64 | {"ver":"1","typ":"ZST","mode":"local"} (base64url) | | nonce_b64 | XChaCha20 192-bit random nonce (base64url) | | ciphertext_b64 | Encrypted claims JSON (base64url) | | tag_b64 | Poly1305 128-bit auth tag (base64url) |

Performance

Zig-native primitives

| Operation | Latency | Notes | | -------------------- | -------- | -------------------------------------------- | | nanoid() | < 1 µs | Stack buf + 64KB CSPRNG pool, zero alloc | | nanoid.Batch(1000) | < 80 µs | 1 JS↔native crossing, native strings | | Snowflake.Id() | < 0.5 µs | Bit ops + mutex lock | | zst.sign() | < 20 µs | BLAKE2b KDF + XChaCha20-Poly1305 + base64url | | zst.verify() | < 30 µs | base64url decode + AEAD decrypt + claims | | zst.decode() | < 10 µs | Parse only, no crypto | | Binary size | < 500 KB | ReleaseSmall + strip | | npm install | < 3 sec | Prebuilt, no compile |

vs pure-JS (Bun v1.3.14, Linux x64, 1000 iter)

| Scenario | zig-crypto | JS competitor | Speed-up | | ------------ | ---------- | ------------------------------------------- | -------- | | Token sign | 15 µs | 80 µs (jose HS256) | ×5.3 | | Token verify | 26 µs | 102 µs (jose HS256) | ×4.0 | | AEAD encrypt | 15 µs | 40 µs (@noble/ciphers XChaCha20-Poly1305) | ×2.6 | | AEAD decrypt | 12 µs | 12 µs (@noble/ciphers) | ×1.0 |

Why faster? Zig runs the full pipeline in native code with arena-allocated temp memory and no JS object allocations. Pure-JS libs allocate multiple Uint8Array/ArrayBuffer per operation, triggering GC pressure. The gap widens with larger payloads and higher throughput.

Architecture

┌──────────────────────────────────────────────┐
│  index.ts  (runtime arch/platform detection)  │  ← User-facing
├──────────────────────────────────────────────┤
│  N-API C ABI  (src/napi.zig — 12 exports)    │  ← Boundary, marshalling
├──────────────────────────────────────────────┤
│  Zig Core Engine                              │  ← Zero-allocation
│  ├── src/id/nanoid.zig                        │
│  ├── src/id/snowflake.zig                     │
│  ├── src/codec/{base64,base58,hex}.zig        │
│  └── src/token/{zst,claims,xchacha20}.zig     │
├──────────────────────────────────────────────┤
│  Crypto Primitives                            │
│  ├── src/crypto/blake2b.zig  (KDF)           │
│  ├── src/crypto/rand.zig     (CSPRNG pool)   │
│  └── src/token/xchacha20.zig (AEAD cipher)   │
├──────────────────────────────────────────────┤
│  src/translate.zig                            │  ← N-API helpers
└──────────────────────────────────────────────┘

CSPRNG: 64KB threadlocal pool refilled via OS entropy (getrandom/arc4random_buf/BCryptGenRandom). Snowflake: Mutex-protected sequence for thread safety across Worker Threads. ZST: XChaCha20-Poly1305 AEAD + BLAKE2b KDF for domain separation. Inspired by PASETO. rev counter for O(1) revocation. Arena allocator per N-API call — all temp memory freed at once on return.

Supported Platforms

| Platform | Arch | Binary | | -------- | ---------- | ----------------- | | Linux | x64, ARM64 | libzig_id.so | | macOS | x64, ARM64 | libzig_id.dylib | | Windows | x64 | zig_id.dll |

Requires Node.js 18+. Runtime loader auto-detects arch, platform, and Linux glibc/musl ABI.

Build from Source

Requires Zig 0.11+.

npm install
zig build -Doptimize=ReleaseSmall -Dnapi-include=node_modules/node-api-headers/include
mkdir -p dist/bin/$(uname -m)-$(uname -s | tr '[:upper:]' '[:lower:]')
cp zig-out/lib/libzig_id.* dist/bin/*/zig-id.node
npm test

Cross-compilation:

zig build -Dtarget=x86_64-linux-gnu    # Linux x64
zig build -Dtarget=aarch64-linux-gnu   # Linux ARM64
zig build -Dtarget=x86_64-macos        # macOS x64
zig build -Dtarget=aarch64-macos       # macOS ARM64
zig build -Dtarget=x86_64-windows-gnu  # Windows x64

License

MIT