asherah

asherah

Node.js bindings for the Asherah envelope encryption and key rotation library.

Prebuilt native binaries are published to npm for Linux (x64/ARM64, glibc and musl), macOS (x64/ARM64), and Windows (x64/ARM64). The correct binary is selected automatically at install time. No compilation needed.

Installation

npm install asherah

Requires Node.js >= 18.

Documentation

Task-oriented walkthroughs under docs/:

Guide	When to read
Getting started	First-time install through round-trip encrypt/decrypt.
Framework integration	Express, Fastify, NestJS, Koa, AWS Lambda, worker patterns.
AWS production setup	KMS keys, DynamoDB, IAM policy, region routing.
Testing	Jest/Vitest fixtures, Testcontainers, mocking patterns.
Troubleshooting	Common errors with what to check first.

Choosing an API style

Two API styles are exposed; both are fully supported and produce the same wire format. New code should prefer the Factory / Session API.

Style	When to use
Static / module-level (asherah.setup, asherah.encrypt, …)	Drop-in compatibility with the canonical godaddy/asherah-node package. Simplest call surface. Singleton lifecycle (setup() once, shutdown() once).
Factory / Session (new SessionFactory(...), factory.getSession(...))	Recommended for new code. Explicit lifecycle, no hidden singleton, multi-tenant isolation is obvious in code.

A complete runnable example exercising both styles plus async, log hook, and metrics hook is in samples/node/index.mjs.

Quick start (static API)

const asherah = require('asherah');

process.env.STATIC_MASTER_KEY_HEX = '22'.repeat(32); // testing only

asherah.setup({
  serviceName: 'my-service',
  productId: 'my-product',
  metastore: 'memory',   // testing only — use 'rdbms' or 'dynamodb' in production
  kms: 'static',         // testing only — use 'aws' in production
});

const ct = asherah.encryptString('user-42', 'secret');
const pt = asherah.decryptString('user-42', ct);

asherah.shutdown();

Quick start (factory / session API)

const { SessionFactory } = require('asherah');

const factory = new SessionFactory({
  serviceName: 'my-service',
  productId: 'my-product',
  metastore: 'memory',
  kms: 'static',
});
const session = factory.getSession('user-42');
try {
  const ct = session.encryptString('secret');
  const pt = session.decryptString(ct);
} finally {
  session.close();
  factory.close();
}

Async API

Every sync function has a *Async counterpart that returns a Promise and runs on the Rust tokio runtime — the Node event loop is not blocked.

await asherah.setupAsync(config);
const ct = await asherah.encryptStringAsync('user-42', 'secret');
const pt = await asherah.decryptStringAsync('user-42', ct);
await asherah.shutdownAsync();

Metastore	Async path	Blocks event loop?
In-memory	tokio worker thread	No
DynamoDB	true async AWS SDK calls on tokio	No
MySQL	spawn_blocking (sync driver on tokio thread pool)	No
Postgres	spawn_blocking (sync driver on tokio thread pool)	No

Tradeoff: ~12µs async vs ~1µs sync per call (hot cache, 64 B payload). Use sync in tight loops where latency matters; async when you need to keep the event loop responsive.

Observability hooks

Log hook

Receive every log event from the Rust core (encrypt/decrypt path, metastore drivers, KMS clients).

asherah.setLogHook((event) => {
  // event = { level, message, target }
  // level ∈ 'trace' | 'debug' | 'info' | 'warn' | 'error'
  if (event.level === 'warn' || event.level === 'error') {
    console.error(`[asherah ${event.level}] ${event.message}`);
  }
});

// later, to deregister:
asherah.setLogHook(null);

The snake_case alias set_log_hook also accepts the canonical (level: number, message: string) signature for backward compatibility with the Go-based asherah npm package.

asherah.set_log_hook((level, message) => {
  // level is a number 0..4 (0=trace, 1=debug, 2=info, 3=warn, 4=error)
  console.log(`[level ${level}] ${message}`);
});

Log events are delivered via N-API ThreadsafeFunction — they run on the Node main thread, so synchronous code in the callback is safe.

Metrics hook

Receive timing events for encrypt/decrypt/store/load and counter events for cache hit/miss/stale.

asherah.setMetricsHook((event) => {
  switch (event.type) {
    case 'encrypt':
    case 'decrypt':
    case 'store':
    case 'load':
      // event = { type, durationNs }
      myHistogram.observe(event.type, event.durationNs / 1e6);
      break;
    case 'cache_hit':
    case 'cache_miss':
    case 'cache_stale':
      // event = { type, name }
      myCounter.inc({ result: event.type, cache: event.name });
      break;
  }
});

// later:
asherah.setMetricsHook(null);

Metrics collection is enabled automatically when a hook is installed, and disabled when cleared.

Input contract

Partition ID (null, undefined, ""): always rejected as programming errors with TypeError (sync) or rejected Promise (async). No row is ever written to the metastore under a degenerate partition ID.

Plaintext to encrypt:

• null / undefined → TypeError from N-API marshalling (sync) or rejected Promise (async).
• Empty string ("") and Buffer.alloc(0) are valid plaintexts. encrypt(...) / encryptString(...) produces a real DataRowRecord envelope; the matching decrypt(...) returns exactly "" or an empty Buffer.

Ciphertext to decrypt:

• null / undefined → TypeError.
• Empty string / empty Buffer → Error from native layer (not valid DataRowRecord JSON).

Do not short-circuit empty plaintext encryption in caller code — empty data is real data, encrypting it produces a genuine envelope, and skipping encryption leaks the fact that the value was empty. See docs/input-contract.md for the full rationale.

Configuration

All fields can be passed in camelCase (native) or PascalCase (canonical Go SDK) — both are auto-mapped. Pass to setup(), setupAsync(), or the SessionFactory constructor.

Field	Type	Default	Description
serviceName	string	required	Service identifier for the key hierarchy.
productId	string	required	Product identifier for the key hierarchy.
metastore	'memory' | 'rdbms' | 'dynamodb'	required	'memory' is testing-only and does not persist across processes.
kms	'static' | 'aws'	'static'	'static' is testing-only (uses a hard-coded master key).
connectionString	string		Connection string for rdbms metastore.
sqlMetastoreDbType	'mysql' | 'postgres'		SQL driver.
enableSessionCaching	boolean	true	Cache Session objects by partition ID.
sessionCacheMaxSize	number	1000	Max cached sessions.
sessionCacheDuration	number		Session cache TTL in seconds.
regionMap	Record<string, string>		AWS KMS multi-region key ARN map.
preferredRegion	string		Preferred AWS region from regionMap.
awsProfileName	string		AWS credentials profile name for KMS/DynamoDB/Secrets Manager clients.
enableRegionSuffix	boolean		Append AWS region suffix to key IDs.
expireAfter	number	90 days	Intermediate-key expiration in seconds.
checkInterval	number	60 minutes	Revoke-check interval in seconds.
dynamoDbEndpoint	string		DynamoDB endpoint URL (for local DynamoDB).
dynamoDbRegion	string		AWS region for DynamoDB.
dynamoDbTableName	string	'EncryptionKey'	DynamoDB table name.
dynamoDbSigningRegion	string		Region used for SigV4 signing.
replicaReadConsistency	'eventual' | 'global' | 'session'		DynamoDB read consistency.
verbose	boolean	false	Emit verbose log events (use a log hook to consume).
enableCanaries	boolean	false	Enable in-memory canary buffers around plaintexts.
disableZeroCopy	boolean		Compatibility shim — accepted but no effect.
nullDataCheck	boolean		Compatibility shim — accepted but no effect.
poolMaxOpen	number	0	Max open DB connections (0 = unlimited).
poolMaxIdle	number	2	Max idle DB connections to retain.
poolMaxLifetime	number	0	Max connection lifetime in seconds (0 = unlimited).
poolMaxIdleTime	number	0	Max idle time in seconds per connection (0 = unlimited).

Environment variables

Variable	Effect
STATIC_MASTER_KEY_HEX	64 hex chars (32 bytes) for static KMS. Testing only.
ASHERAH_NODE_DEBUG=1	Enable native-side debug logging.
ASHERAH_POOL_MAX_OPEN	Override poolMaxOpen.
ASHERAH_POOL_MAX_IDLE	Override poolMaxIdle.
ASHERAH_POOL_MAX_LIFETIME	Override poolMaxLifetime.
ASHERAH_POOL_MAX_IDLE_TIME	Override poolMaxIdleTime.

Performance

Native Rust implementation compiled via napi-rs. Typical latencies on Apple M4 Max (in-memory metastore, session caching enabled, 64-byte payload):

Operation	Sync	Async
Encrypt	~970 ns	~12 µs
Decrypt	~1.2 µs	~12 µs

See scripts/benchmark.sh for head-to-head comparisons with the canonical Go-based implementation.

Migration from the canonical Go-based asherah (v3.x)

Drop-in replacement. The npm wrapper provides full backward compatibility:

• PascalCase config — ServiceName, ProductID, Metastore, etc. are auto-mapped to camelCase.
• snake_case function aliases — set_log_hook, set_metrics_hook, get_setup_status, encrypt_string, decrypt_string_async, etc.
• Metastore/KMS aliases — 'test-debug-memory', 'test-debug-static' normalize to the short forms.
• set_log_hook signature variants — both the canonical (level: number, message: string) and the structured (event: { level, message, target }) are supported.

To migrate: change your dependency from asherah@^3 to this package. No code changes required.

Supported platforms

Platform	Architecture	Notes
Linux	x64	glibc (most distros)
Linux	x64	musl (Alpine)
Linux	ARM64	glibc
Linux	ARM64	musl (Alpine)
macOS	x64	Intel
macOS	ARM64	Apple Silicon
Windows	x64	MSVC
Windows	ARM64	MSVC

API Reference

Full TSDoc lives in index.d.ts and surfaces in your IDE on hover. The tables below summarize each API; the type file is the source of truth.

Static / module-level API (legacy compatibility)

Lifecycle

Function	Description
setup(config)	Initialize the global instance. Throws if already configured.
setupAsync(config)	Async variant. Returns Promise<void>.
shutdown()	Tear down the global instance and clear cached sessions. Idempotent.
shutdownAsync()	Async variant. Returns Promise<void>.
getSetupStatus()	boolean — true if setup() has been called and shutdown() has not.
setenv(envJson)	Apply env vars from a JSON string before setup(). Mirrors the canonical SDK.

Encrypt / decrypt

Function	Param 1	Param 2	Returns
encrypt(partitionId, data)	string (non-empty)	Buffer (empty OK)	string (DRR JSON)
encryptAsync(partitionId, data)	string	Buffer	Promise<string>
encryptString(partitionId, data)	string	string (empty OK)	string (DRR JSON)
encryptStringAsync(partitionId, data)	string	string	Promise<string>
decrypt(partitionId, drr)	string	string (DRR JSON)	Buffer
decryptAsync(partitionId, drr)	string	string	Promise<Buffer>
decryptString(partitionId, drr)	string	string	string
decryptStringAsync(partitionId, drr)	string	string	Promise<string>

All accept the snake_case aliases encrypt_async, encrypt_string, encrypt_string_async, decrypt_async, decrypt_string, decrypt_string_async, setup_async, shutdown_async, get_setup_status.

Hooks

Function	Description
setLogHook(cb) / set_log_hook(cb)	Register a structured-event log callback. Pass null to deregister. The snake_case alias also accepts the canonical (level, message) signature.
setMetricsHook(cb) / set_metrics_hook(cb)	Register a metrics callback. Pass null to deregister.

Factory / Session API (recommended)

class SessionFactory

Member	Description
new SessionFactory(config)	Construct from inline config.
static SessionFactory.fromEnv()	Construct from environment variables.
factory.getSession(partitionId)	Get a per-partition session. Throws on null/empty partition.
factory.close()	Release native resources. After close, getSession() throws.

class AsherahSession

Member	Description
session.encrypt(data)	Buffer → DRR JSON string. Empty Buffer is valid.
session.encryptString(data)	string → DRR JSON string. Empty string is valid.
session.decrypt(drr)	DRR JSON string → Buffer.
session.decryptString(drr)	DRR JSON string → string.
session.close()	Release native resources.

Type aliases

type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error';

type LogEvent = {
  level: LogLevel;
  message: string;
  target: string;
};

type MetricsEvent =
  | { type: 'encrypt' | 'decrypt' | 'store' | 'load'; durationNs: number }
  | { type: 'cache_hit' | 'cache_miss' | 'cache_stale'; name: string };

Compatibility shims

setMaxStackAllocItemSize(n) and setSafetyPaddingOverhead(n) are accepted for parity with the canonical Go-based asherah-node package but have no effect in this Rust binding.

License

Licensed under the Apache License, Version 2.0.