@kokuin/crypto-napi 0.0.0-stage → 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Paul Le Cam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,62 @@
-# Temporary Holding Version
+# @kokuin/crypto-napi
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Strict asynchronous crypto provider for Node.js, backed by the kokuin Rust core (`crates/kokuin-crypto`) through Node-API.
+It implements the `@kokuin/crypto` `CryptoProvider` contract and falls back to `@kokuin/crypto-node` when no native binary loads.
+
+```ts
+import { createNapiCrypto } from '@kokuin/crypto-napi'
+
+const crypto = createNapiCrypto()
+crypto.backend // 'napi', or 'node' after a fallback; `crypto.failure` then says why
+const signature = await crypto.sign({ alg: 'EdDSA', privateKey: seed, message })
+```
+
+| Call | Route |
+| --- | --- |
+| Ed25519 `sign`, Ed25519 `verify`, `blake3` | Native, on the calling thread |
+| ES256 `verify` and ES256 items of `verifyBatch` | `nodeCrypto` (OpenSSL), about three times faster than the Rust P-256 verifier |
+| `verifyBatch` with two or more Ed25519 items | Native on the libuv thread pool; inputs are copied before the Promise returns |
+| One-item `verifyBatch`, `signBatch` up to 32 items, `blake3Batch` up to 1 MiB | Native, on the calling thread, where the pool hop costs more than it saves |
+| Larger `signBatch` and `blake3Batch` | Native on the libuv thread pool |
+
+The routes come from the [Node crypto benchmark gate](../../docs/reference/crypto-node-benchmark.md).
+
+Measured through the provider on one x86_64 container with Node 22, against strict noble:
+Ed25519 signing is about 18× faster, Ed25519 verification about 25×, and blake3 on 64 KiB about 110×.
+A batch of 32 Ed25519 verifications costs about 113 µs per item and keeps the event loop free.
+
+The backend is chosen once, when `createNapiCrypto()` runs. A missing binary, a binary built for another ABI version
+or one that fails to load selects `nodeCrypto`. A native failure after construction rejects; it never falls back.
+
+Arguments are validated in JavaScript exactly as `nobleCrypto` validates them, so every backend raises the same errors.
+Every backend accepts and rejects exactly the same signatures: the shared corpus and the pinned upstream vectors run
+against the Rust core, strict noble, `nodeCrypto` and this provider.
+
+Prebuilt binaries are not published yet. In this repository, `pnpm --filter @kokuin/crypto-napi run build:native`
+compiles one for the current host into `native/`. Requires Node.js 22 or later.
+
+## Named params migration
+
+`CryptoProvider.verify` now accepts one `VerifyItem`: `{ alg, signature, message, publicKey }`.
+`sign`, `signBatch`, `blake3` and `blake3Batch` take flat params objects.
+`verifyBatch` retains its single array argument.
+
+| Export | Named params type | Fields |
+| --- | --- | --- |
+| `NapiBinding.sign` | `NapiBindingSignParams` | `seed, message` |
+| `NapiBinding.signBatch` | `Array<NapiBindingSignParams>` | `seeds, messages` |
+| `NapiBinding.blake3` | `NapiBindingBlake3Params` | `input, length` |
+| `NapiBinding.blake3Batch` | `NapiBindingBlake3BatchParams` | `inputs, length` |
+| `NapiBinding.verify` | `NapiVerifyParams` | `es256, signature, message, publicKey` |
+| `NapiBinding.verifyBatch` | `Array<NapiVerifyParams>` | `es256, signatures, messages, publicKeys` |
+
+`NapiBinding` accepts named signing, hashing and verification objects. The loader adapts them to the unchanged positional native ABI.
+
+These signature and typing changes preserve cryptographic results, error causes, ordering and storage behaviour.
+
+| API | Named params type | Previous positional form |
+| --- | --- | --- |
+| `CryptoProvider.sign` | `CryptoProviderSignParams` | `sign(alg, privateKey, message)` |
+| `CryptoProvider.signBatch` | `CryptoProviderSignBatchParams` | `signBatch(alg, items)` |
+| `CryptoProvider.blake3` | `CryptoProviderBlake3Params` | `blake3(input, dkLen)` |
+| `CryptoProvider.blake3Batch` | `CryptoProviderBlake3BatchParams` | `blake3Batch(inputs, dkLen)` |

package/lib/binding.d.ts

@@ -0,0 +1,44 @@
+export type NapiVerifyParams = {
+    es256: boolean;
+    signature: Uint8Array;
+    message: Uint8Array;
+    publicKey: Uint8Array;
+};
+/** The ABI the provider expects from `crates/kokuin-crypto-napi` (its `ABI_VERSION`). */
+export declare const NAPI_ABI_VERSION = 1;
+export type NapiBindingSignParams = {
+    seed: Uint8Array;
+    message: Uint8Array;
+};
+export type NapiBindingBlake3Params = {
+    input: Uint8Array;
+    length: number;
+};
+export type NapiBindingBlake3BatchParams = {
+    inputs: Array<Uint8Array>;
+    length: number;
+};
+export type NapiBinding = {
+    ABI_VERSION: number;
+    sign(params: NapiBindingSignParams): Uint8Array;
+    verify(params: NapiVerifyParams): boolean;
+    blake3(params: NapiBindingBlake3Params): Uint8Array;
+    signBatch(items: Array<NapiBindingSignParams>): Promise<Array<Uint8Array>>;
+    verifyBatch(items: Array<NapiVerifyParams>): Promise<Array<boolean>>;
+    blake3Batch(params: NapiBindingBlake3BatchParams): Promise<Array<Uint8Array>>;
+};
+/** Why no native binding loaded, or `undefined` when one did. */
+export type NapiLoadFailure = {
+    reason: 'missing' | 'abi' | 'load';
+    path: string;
+    cause?: unknown;
+};
+/** The platform suffix of the binary file name, such as `linux-x64-gnu` or `darwin-arm64`. */
+export declare function napiTarget(): string;
+/** Where the binary for this platform is expected: `native/kokuin-crypto-napi.<target>.node`. */
+export declare function napiBindingPath(): string;
+/** Load the native binding once per process. Never throws; reports why it could not load. */
+export declare function loadNapiBinding(): {
+    binding: NapiBinding | null;
+    failure?: NapiLoadFailure;
+};

package/lib/binding.js

@@ -0,0 +1,72 @@
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** The ABI the provider expects from `crates/kokuin-crypto-napi` (its `ABI_VERSION`). */ export const NAPI_ABI_VERSION = 1;
+function adaptBinding(native) {
+    return {
+        ABI_VERSION: native.ABI_VERSION,
+        sign: ({ seed, message })=>native.sign(seed, message),
+        // The native ABI takes parallel arrays. Split here so nothing above it can misalign entries.
+        signBatch: (items)=>{
+            return native.signBatch(items.map((item)=>item.seed), items.map((item)=>item.message));
+        },
+        blake3: ({ input, length })=>native.blake3(input, length),
+        blake3Batch: ({ inputs, length })=>native.blake3Batch(inputs, length),
+        verify: ({ es256, signature, message, publicKey })=>{
+            return native.verify(es256, signature, message, publicKey);
+        },
+        verifyBatch: (items)=>{
+            return native.verifyBatch(items.map((item)=>item.es256), items.map((item)=>item.signature), items.map((item)=>item.message), items.map((item)=>item.publicKey));
+        }
+    };
+}
+function libc() {
+    const header = process.report?.getReport()?.header;
+    return header?.glibcVersionRuntime ? 'gnu' : 'musl';
+}
+/** The platform suffix of the binary file name, such as `linux-x64-gnu` or `darwin-arm64`. */ export function napiTarget() {
+    const base = `${process.platform}-${process.arch}`;
+    return process.platform === 'linux' ? `${base}-${libc()}` : base;
+}
+/** Where the binary for this platform is expected: `native/kokuin-crypto-napi.<target>.node`. */ export function napiBindingPath() {
+    const root = join(dirname(fileURLToPath(import.meta.url)), '..');
+    return join(root, 'native', `kokuin-crypto-napi.${napiTarget()}.node`);
+}
+let cached;
+/** Load the native binding once per process. Never throws; reports why it could not load. */ export function loadNapiBinding() {
+    if (cached != null) return cached;
+    const path = napiBindingPath();
+    if (!existsSync(path)) {
+        cached = {
+            binding: null,
+            failure: {
+                reason: 'missing',
+                path
+            }
+        };
+        return cached;
+    }
+    try {
+        const binding = createRequire(import.meta.url)(path);
+        cached = binding.ABI_VERSION === NAPI_ABI_VERSION ? {
+            binding: adaptBinding(binding)
+        } : {
+            binding: null,
+            failure: {
+                reason: 'abi',
+                path
+            }
+        };
+    } catch (cause) {
+        cached = {
+            binding: null,
+            failure: {
+                reason: 'load',
+                path,
+                cause
+            }
+        };
+    }
+    return cached;
+}

package/lib/index.d.ts

@@ -0,0 +1,4 @@
+export type { NapiBinding, NapiBindingBlake3BatchParams, NapiBindingBlake3Params, NapiBindingSignParams, NapiLoadFailure, NapiVerifyParams, } from './binding.js';
+export { loadNapiBinding, NAPI_ABI_VERSION, napiBindingPath, napiTarget } from './binding.js';
+export type { NapiCrypto, NapiCryptoOptions } from './provider.js';
+export { BLAKE3_SYNC_BATCH_BYTES, createNapiCrypto, SIGN_SYNC_BATCH_ITEMS } from './provider.js';

package/lib/index.js

@@ -0,0 +1,2 @@
+export { loadNapiBinding, NAPI_ABI_VERSION, napiBindingPath, napiTarget } from './binding.js';
+export { BLAKE3_SYNC_BATCH_BYTES, createNapiCrypto, SIGN_SYNC_BATCH_ITEMS } from './provider.js';

package/lib/provider.d.ts

@@ -0,0 +1,30 @@
+import type { CryptoProvider } from '@kokuin/crypto';
+import { type NapiBinding, type NapiLoadFailure } from './binding.js';
+export type NapiCrypto = CryptoProvider & {
+    /** `napi` when the Rust binding loaded, `node` when the provider fell back to `nodeCrypto`. */
+    readonly backend: 'napi' | 'node';
+    /** Why the binding did not load, when `backend` is `node`. */
+    readonly failure?: NapiLoadFailure;
+};
+export type NapiCryptoOptions = {
+    /** Use this binding instead of loading one. `null` forces the `nodeCrypto` fallback. */
+    binding?: NapiBinding | null;
+};
+/**
+ * blake3 batches with at most this much input in total hash on the calling thread. Below it the
+ * thread-pool hop and input copies cost more than the hashing (1 MiB hashes in about 135 µs on
+ * x86_64); above it, the pool keeps a large hash off the event loop.
+ */
+export declare const BLAKE3_SYNC_BATCH_BYTES: number;
+/**
+ * Ed25519 signing batches of at most this many items sign on the calling thread: about 27 µs per
+ * signature at 256 B and 61 µs at 12 KiB on x86_64, against a thread-pool hop that measured
+ * slower for every batch the gate covers. Larger batches go to the pool.
+ */
+export declare const SIGN_SYNC_BATCH_ITEMS = 32;
+/**
+ * The Rust core through Node-API when this platform's binary loads, otherwise `nodeCrypto`.
+ * The choice is made once, here; a native failure after construction rejects instead of
+ * falling back.
+ */
+export declare function createNapiCrypto(options?: NapiCryptoOptions): NapiCrypto;

package/lib/provider.js

@@ -0,0 +1,198 @@
+import { nodeCrypto } from '@kokuin/crypto-node';
+import { loadNapiBinding } from './binding.js';
+function assertBytes(value) {
+    if (!(value instanceof Uint8Array) || !(value.buffer instanceof ArrayBuffer)) {
+        throw new TypeError('Expected an unshared Uint8Array');
+    }
+    // Throws TypeError on a detached buffer.
+    new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+}
+function assertSigning(alg, seed, message) {
+    if (alg !== 'EdDSA') throw new TypeError('Unsupported signing algorithm');
+    assertBytes(seed);
+    assertBytes(message);
+    if (seed.length !== 32) throw new TypeError('Expected a 32-byte Ed25519 seed');
+}
+function assertVerifying({ alg, signature, message, publicKey }) {
+    if (alg !== 'EdDSA' && alg !== 'ES256') throw new TypeError('Unsupported verification algorithm');
+    for (const bytes of [
+        signature,
+        message,
+        publicKey
+    ])assertBytes(bytes);
+}
+function assertOutputLength(dkLen) {
+    if (!Number.isInteger(dkLen) || dkLen < 1 || dkLen > 65536) throw new RangeError('Invalid blake3 output length');
+}
+/**
+ * blake3 batches with at most this much input in total hash on the calling thread. Below it the
+ * thread-pool hop and input copies cost more than the hashing (1 MiB hashes in about 135 µs on
+ * x86_64); above it, the pool keeps a large hash off the event loop.
+ */ export const BLAKE3_SYNC_BATCH_BYTES = 1024 * 1024;
+/**
+ * Ed25519 signing batches of at most this many items sign on the calling thread: about 27 µs per
+ * signature at 256 B and 61 µs at 12 KiB on x86_64, against a thread-pool hop that measured
+ * slower for every batch the gate covers. Larger batches go to the pool.
+ */ export const SIGN_SYNC_BATCH_ITEMS = 32;
+function assertResultCount(results, count) {
+    if (results.length !== count) throw new Error('Invalid native crypto response count');
+    return results;
+}
+/**
+ * Routes, set by the Node crypto benchmark gate (scripts/bench-crypto-node.mjs):
+ * - Ed25519 sign, Ed25519 verify and blake3 single calls run natively on the calling thread.
+ * - ES256 verification, single or batched, uses `nodeCrypto`: OpenSSL is about three times
+ *   faster than the Rust P-256 verifier.
+ * - Ed25519 verify batches of two or more copy their inputs on the calling thread, then run
+ *   natively on the libuv pool, keeping about 100 µs per item off the event loop. A one-item
+ *   batch runs on the calling thread, where it is faster than the pool hop.
+ * - Ed25519 sign batches run natively on the calling thread up to `SIGN_SYNC_BATCH_ITEMS` items
+ *   and on the pool above it.
+ * - blake3 batches run natively on the calling thread up to `BLAKE3_SYNC_BATCH_BYTES` of input
+ *   and on the pool above it.
+ *
+ * Arguments are validated in JavaScript exactly as `nobleCrypto` validates them, so every
+ * backend raises the same error types. Every method consumes its inputs before its Promise
+ * returns.
+ */ function napiProvider(binding) {
+    return {
+        async sign ({ alg, privateKey: seed, message }) {
+            assertSigning(alg, seed, message);
+            return binding.sign({
+                seed,
+                message
+            });
+        },
+        async signBatch ({ alg, items }) {
+            if (alg !== 'EdDSA') throw new TypeError('Unsupported signing algorithm');
+            for (const item of items)assertSigning(alg, item.privateKey, item.message);
+            if (items.length === 0) return [];
+            // Signing is cheap enough that the pool hop costs more than it saves for ordinary batches,
+            // and the calling-thread route still takes half nodeCrypto's main-thread time.
+            if (items.length <= SIGN_SYNC_BATCH_ITEMS) {
+                return items.map((item)=>binding.sign({
+                        seed: item.privateKey,
+                        message: item.message
+                    }));
+            }
+            // Capture the count before suspending: the caller may change the array afterwards.
+            const count = items.length;
+            const results = await binding.signBatch(items.map((item)=>({
+                    seed: item.privateKey,
+                    message: item.message
+                })));
+            return assertResultCount(results, count);
+        },
+        async verify ({ alg, signature, message, publicKey }) {
+            assertVerifying({
+                alg,
+                signature,
+                message,
+                publicKey
+            });
+            if (alg === 'ES256') return await nodeCrypto.verify({
+                alg,
+                signature,
+                message,
+                publicKey
+            });
+            return binding.verify({
+                es256: false,
+                signature,
+                message,
+                publicKey
+            });
+        },
+        async verifyBatch (items) {
+            for (const item of items){
+                assertVerifying({
+                    alg: item.alg,
+                    signature: item.signature,
+                    message: item.message,
+                    publicKey: item.publicKey
+                });
+            }
+            // Capture membership before suspending: the caller may change the array afterwards.
+            const algs = items.map((item)=>item.alg);
+            const ed25519 = items.filter((item)=>item.alg === 'EdDSA');
+            // Start both halves before awaiting either: nodeCrypto consumes its inputs synchronously
+            // and the native batch copies them, so caller mutations afterwards change nothing.
+            const es256 = items.filter((item)=>item.alg === 'ES256').map((item)=>{
+                return nodeCrypto.verify({
+                    alg: 'ES256',
+                    signature: item.signature,
+                    message: item.message,
+                    publicKey: item.publicKey
+                });
+            });
+            const native = ed25519.length === 0 ? Promise.resolve([]) : ed25519.length === 1 ? Promise.resolve([
+                binding.verify({
+                    es256: false,
+                    signature: ed25519[0].signature,
+                    message: ed25519[0].message,
+                    publicKey: ed25519[0].publicKey
+                })
+            ]) : binding.verifyBatch(ed25519.map((item)=>({
+                    es256: false,
+                    signature: item.signature,
+                    message: item.message,
+                    publicKey: item.publicKey
+                }))).then((results)=>assertResultCount(results, ed25519.length));
+            const [edResults, esResults] = await Promise.all([
+                native,
+                Promise.all(es256)
+            ]);
+            let ed = 0;
+            let es = 0;
+            return algs.map((alg)=>{
+                return alg === 'EdDSA' ? edResults[ed++] : esResults[es++];
+            });
+        },
+        async blake3 ({ input, dkLen }) {
+            assertBytes(input);
+            assertOutputLength(dkLen);
+            return binding.blake3({
+                input,
+                length: dkLen
+            });
+        },
+        async blake3Batch ({ inputs, dkLen }) {
+            assertOutputLength(dkLen);
+            for (const input of inputs)assertBytes(input);
+            if (inputs.length === 0) return [];
+            const total = inputs.reduce((sum, input)=>sum + input.length, 0);
+            if (total <= BLAKE3_SYNC_BATCH_BYTES) return inputs.map((input)=>binding.blake3({
+                    input,
+                    length: dkLen
+                }));
+            const count = inputs.length;
+            return assertResultCount(await binding.blake3Batch({
+                inputs,
+                length: dkLen
+            }), count);
+        }
+    };
+}
+/**
+ * The Rust core through Node-API when this platform's binary loads, otherwise `nodeCrypto`.
+ * The choice is made once, here; a native failure after construction rejects instead of
+ * falling back.
+ */ export function createNapiCrypto(options = {}) {
+    const loaded = options.binding !== undefined ? {
+        binding: options.binding
+    } : loadNapiBinding();
+    if (loaded.binding == null) {
+        const failure = 'failure' in loaded ? loaded.failure : undefined;
+        return {
+            ...nodeCrypto,
+            backend: 'node',
+            ...failure ? {
+                failure
+            } : {}
+        };
+    }
+    return {
+        ...napiProvider(loaded.binding),
+        backend: 'napi'
+    };
+}

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@kokuin/crypto-napi",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.7.0",
+  "description": "Strict asynchronous crypto provider backed by the Rust core through Node-API, falling back to @kokuin/crypto-node",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TairuFramework/kokuin",
+    "directory": "packages/crypto-napi"
+  },
+  "license": "MIT",
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": "./lib/index.js"
+  },
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "files": [
+    "lib/*",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@kokuin/crypto": "^0.7.0",
+    "@kokuin/crypto-node": "^0.7.0"
+  },
+  "devDependencies": {
+    "@kokuin/crypto-conformance": "^0.0.0",
+    "@noble/curves": "^2.4.0",
+    "@noble/hashes": "^2.4.0",
+    "@types/node": "^26.6.6"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "pnpm run build:clean && pnpm run build:js && pnpm run build:types",
+    "build:clean": "del-cli lib",
+    "build:js": "del-cli 'lib/**/*.js' && swc src -d ./lib --config-file ../../node_modules/@kigu/dev/swc.json --strip-leading-paths",
+    "build:native": "node ../../scripts/build-crypto-napi.mjs",
+    "build:types": "del-cli 'lib/**/*.d.ts' 'lib/**/*.d.ts.map' && tsc --emitDeclarationOnly --skipLibCheck",
+    "test": "pnpm run test:types && pnpm run test:unit",
+    "test:native": "vitest run test/native.test.ts",
+    "test:types": "tsc --noEmit --skipLibCheck -p tsconfig.test.json",
+    "test:unit": "vitest run --exclude test/native.test.ts"
+  }
 }