dstu-core 0.1.0

package/README.md

@@ -0,0 +1,80 @@
+# dstu-core (Node.js bindings)
+
+**Provisional — not published to npm, not independently audited.** See the root project's
+`docs/SECURITY.md` and `docs/DECISIONS.md` for the full threat model and per-construction status.
+This binding wraps the full `dstu_core::crypto_*` surface (`docs/bindings-strategy.md` T-50) —
+install from source as shown below.
+
+## Installing (from source)
+
+```sh
+npm install
+npm run build
+node -e "require('./js/index.js').selfTest()"
+```
+
+`npm run build` (`napi build native --platform --release`) compiles the Rust addon and generates
+`native/index.js`/`native/index.d.ts`/the platform-specific `*.node` binary — all gitignored,
+regenerated fresh every build (never hand-edited or committed). `js/index.js` is the hand-written
+public entry point: every native export re-exported as-is, plus the idiomatic
+`stream.Transform`-based `SecretStreamEncryptor`/`SecretStreamDecryptor` (D-118) built in pure JS on
+top of them.
+
+`selfTest()` re-runs `dstu_core::selftest::run()` (`docs/TASKS.md` T-161) against the exact
+compiled build and throws if anything official-vector-level is wrong — the first thing to run
+after any build to confirm it actually works, not just compiled.
+
+This crate is its own Cargo workspace, separate from the repo root (`docs/DECISIONS.md` D-119) —
+build/test it from inside this directory, not from the repo root. On Windows, `napi-build`'s
+`gnu`-host path needs a real `libnode.dll` that no prebuilt Node.js distribution ships — if your
+own Rust toolchain defaults to a `-gnu` host (uncommon, but possible), switch to an MSVC toolchain
+for this directory specifically: `rustup override set stable-x86_64-pc-windows-msvc` (see
+`docs/DECISIONS.md` D-125/D-130 for why this is a machine-local fix, not something committed here).
+
+## Usage
+
+Every function/class below is a named export of `js/index.js` (`require('dstu-core')` once
+published, `require('../js/index.js')` from inside this repo). See `examples/` for complete,
+runnable scripts, and `test/` for the full correctness/rejection/misuse suite each one is verified
+against (D-64/D-65).
+
+```js
+const dstu = require('./js/index.js');
+
+const key = dstu.secretboxKeygen();
+const sealed = dstu.secretboxSeal(key, Buffer.from('a message worth protecting'));
+console.log(dstu.secretboxOpen(key, sealed).toString()); // "a message worth protecting"
+```
+
+| Module | Functions/classes | Notes |
+|---|---|---|
+| `crypto_secretbox` | `secretboxKeygen`, `secretboxSeal`, `secretboxOpen` | Single-message authenticated encryption. `examples/secretbox.js`. |
+| `crypto_box` | `boxKeygen`, `boxPublicKey`, `boxSeal`, `boxOpen` | Public-key encryption (hybrid via KDF over `hazmat::dstu9041`, `l(p)=256`, D-169). `boxSeal`/`boxOpen` are not memory-bounded — the whole message is held in memory. `examples/box.js`. |
+| `crypto_box512` | `box512Keygen`, `box512PublicKey`, `box512Seal`, `box512Open` | `l(p)=512`/E512/1 sibling of `crypto_box` (T-193/T-204). `examples/box512.js`. |
+| `crypto_secretstream` | `secretstreamKeygen`, `SecretStreamPushState`, `SecretStreamPullState`, `SecretStreamEncryptor`, `SecretStreamDecryptor` | Chunked streaming AEAD. The `stream.Transform` `SecretStreamEncryptor`/`SecretStreamDecryptor` wire format matches `uacrypt encrypt`/`decrypt` exactly (D-118). `examples/secretstream-file.js`. |
+| `crypto_sign` | `signKeygen`, `signVerifyingKey`, `signMessage`, `signVerify` | DSTU 4145 `m=163` digital signatures, deterministic nonce (no RNG dependency). `examples/sign.js`. |
+| `crypto_sign257` | `sign257Keygen`, `sign257VerifyingKey`, `sign257Message`, `sign257Verify` | `m=257` sibling of `crypto_sign` (T-199/T-204) — the curve real Diia-issued qualified signatures use. `examples/sign257.js`. |
+| `crypto_pwhash` | `pwhashHashPassword`, `pwhashVerifyPassword`, `PWHASH_INTERACTIVE`/`PWHASH_MODERATE`/`PWHASH_SENSITIVE` | Argon2id (the one deliberately non-DSTU component, D-49/D-50). `examples/password-hashing.js`. |
+| `crypto_auth` | `authKeygen`, `auth`, `authVerify` | Keyed message authentication (Kupyna-KMAC). `examples/misc.js`. |
+| `crypto_kdf` | `kdfKeygen`, `kdfDeriveSubkey` | Deterministic subkey derivation. `subkeyId` is a plain non-negative `number`, not `BigInt`. `examples/misc.js`. |
+| `crypto_generichash` | `kupyna256`, `kupyna512`, `Kupyna256Hasher`, `Kupyna512Hasher` | One-shot and streaming Kupyna hashing. `examples/misc.js`. |
+| `crypto_stream` | `streamKeygen`, `streamEncrypt`, `streamDecrypt` | Strumok-256 keystream — **unauthenticated**, `streamDecrypt` never fails on tampered input. `examples/misc.js`. |
+| `randombytes` | `randombytesBuf` | CSPRNG-backed random bytes. `examples/misc.js`. |
+| — | `selfTest` | Runtime KAT self-check (T-161). Every crypto-operation failure throws a plain `Error` carrying the underlying cause's message. |
+
+## Testing
+
+```sh
+node --test
+```
+
+`cargo build -p uacrypt --release` (from the repo root) first if you want
+`test/secretstream.test.js`'s live `uacrypt` CLI interop test to actually run instead of skipping.
+`cargo xtask nodejs` (from the repo root) runs this whole sequence, including that build step, in
+one command.
+
+## Static analysis
+
+`npm run lint` (ESLint, `@eslint/js` recommended rules - `eslint.config.js`) over `js/`/`test/`/
+`examples/`, not `native/` (napi-rs-generated, never hand-edited). A real required CI step
+(`bindings-nodejs.yml`), and part of `cargo xtask nodejs` (T-208).

package/js/index.js

@@ -0,0 +1,25 @@
+'use strict';
+
+/**
+ * Node.js bindings for dstu-core (Ukrainian DSTU cryptographic standards).
+ *
+ * Provisional - not yet published to npm, not independently audited. See the root project's
+ * docs/SECURITY.md and docs/DECISIONS.md for the full threat model and per-construction status
+ * (docs/bindings-strategy.md T-50).
+ *
+ * `../native/index.js` is the napi-rs-generated low-level binding (regenerated by `npm run
+ * build`, never hand-edited or committed - see .gitignore). This file is the public package
+ * entry point: every native export re-exported as-is, plus the idiomatic
+ * `stream.Transform`-based `SecretStreamEncryptor`/`SecretStreamDecryptor` (step 3) layered on
+ * top of the native `SecretStreamPushState`/`SecretStreamPullState` (step 2) in pure JS, no new
+ * Rust glue - mirrors bindings/python/python/dstu_core/__init__.py's own split exactly.
+ */
+
+const native = require('../native/index.js');
+const { SecretStreamEncryptor, SecretStreamDecryptor } = require('./secretstream.js');
+
+module.exports = {
+  ...native,
+  SecretStreamEncryptor,
+  SecretStreamDecryptor,
+};

package/js/secretstream.js

@@ -0,0 +1,175 @@
+'use strict';
+
+/**
+ * Idiomatic `crypto_secretstream` pipeline (docs/DECISIONS.md D-118, docs/bindings-strategy.md
+ * T-50 step 3) - hides chunk/tag/length-prefix bookkeeping behind a `stream.Transform` pair, built
+ * in pure JS on top of the low-level SecretStreamPushState/SecretStreamPullState the native addon
+ * already exposes (step 2), rather than new Rust glue. Mirrors
+ * bindings/python/python/dstu_core/secretstream.py's own design exactly (see D-118's two
+ * standing pitfalls this port re-checks below).
+ *
+ * Wire format matches `uacrypt encrypt`/`decrypt` exactly (crates/uacrypt/src/lib.rs's
+ * run_secretstream_encrypt/run_secretstream_decrypt, D-68): `header (32 bytes)` followed by one
+ * record per chunk, `tagByte (1) || chunkLenU32LE (4) || ciphertext (chunkLen) || authTag (16)`,
+ * chunks capped at 8 KiB (matching SECRETSTREAM_CHUNK_BYTES, not an independent choice).
+ */
+
+const { Transform } = require('node:stream');
+const native = require('../native/index.js');
+
+// Matches crates/uacrypt/src/lib.rs's SECRETSTREAM_CHUNK_BYTES exactly - required for wire-format
+// interop with `uacrypt encrypt`/`decrypt`, not an independent choice.
+const CHUNK_BYTES = 8 * 1024;
+const AUTH_TAG_BYTES = 16;
+
+/**
+ * Write-only Transform: buffers input and pushes each full 8 KiB chunk downstream as it fills,
+ * hiding the header/tag/framing bookkeeping entirely.
+ *
+ * Usage: `fs.createReadStream(inPath).pipe(new SecretStreamEncryptor(key)).pipe(fs.createWriteStream(outPath))`
+ *
+ * D-118 pitfall check #1: this class deliberately overrides only `_flush`, not `_destroy`, to
+ * emit the Final chunk. Node's stream machinery calls `_flush` only when the writable side ends
+ * gracefully (`.end()`) - never on `destroy()`/an upstream error, which instead skips straight to
+ * `_destroy`. So a pipeline that errors partway leaves the output stream without a Final chunk,
+ * and `SecretStreamDecryptor` reading that truncated output fails closed in `_flush` ("stream
+ * ended before a Final chunk") rather than silently accepting a complete-looking but truncated
+ * file - matching this project's standing "no partial output treated as valid on failure" rule
+ * (D-65), the same property Python's own `__exit__` had to be fixed to provide (T-49 step 3).
+ */
+class SecretStreamEncryptor extends Transform {
+  constructor(key, options) {
+    super(options);
+    this._pushState = new native.SecretStreamPushState(key);
+    this._buf = Buffer.alloc(0);
+    this.push(this._pushState.header);
+  }
+
+  _pushChunk(tag, data) {
+    const { ciphertext, authTag } = this._pushState.push(tag, data);
+    const lenBuf = Buffer.alloc(4);
+    lenBuf.writeUInt32LE(data.length, 0);
+    this.push(Buffer.concat([Buffer.from([tag]), lenBuf, ciphertext, authTag]));
+  }
+
+  _transform(chunk, _encoding, callback) {
+    this._buf = Buffer.concat([this._buf, chunk]);
+    let err;
+    try {
+      while (this._buf.length > CHUNK_BYTES) {
+        const piece = this._buf.subarray(0, CHUNK_BYTES);
+        this._buf = this._buf.subarray(CHUNK_BYTES);
+        this._pushChunk(native.SECRETSTREAM_TAG_MESSAGE, piece);
+      }
+    } catch (e) {
+      err = e;
+    }
+    // Deferred via process.nextTick, not called synchronously: Node's own stream docs warn that
+    // invoking _transform's callback synchronously (this method never actually awaits any I/O)
+    // makes an error passed to it throw synchronously out of the triggering write() call instead
+    // of emitting 'error' asynchronously the documented way - confirmed the hard way, a real
+    // deadlock/uncaught-throw found running this suite under node:test, not a defensive guess.
+    process.nextTick(callback, err);
+  }
+
+  _flush(callback) {
+    let err;
+    try {
+      this._pushChunk(native.SECRETSTREAM_TAG_FINAL, this._buf);
+      this._buf = Buffer.alloc(0);
+    } catch (e) {
+      err = e;
+    }
+    process.nextTick(callback, err);
+  }
+}
+
+/**
+ * Read-only Transform: parses and decrypts one chunk at a time from arbitrarily-chunked input,
+ * emitting plaintext downstream. Errors (via the stream's `'error'` event) on authentication
+ * failure or truncation - a dropped/tampered/reordered chunk, or a stream that ends before a
+ * Final chunk, both fail closed rather than yielding wrong plaintext.
+ *
+ * D-118 pitfall check #2: `chunkLen` is untrusted wire input, read before any tag verification -
+ * rejected here the moment it is parsed (before ever buffering up to its declared length), the
+ * same `CliError::SecretstreamChunkTooLarge` bound `uacrypt decrypt` enforces
+ * (crates/uacrypt/src/lib.rs) and Python's own reader re-checked (T-49 step 3). Bytes remaining
+ * after the Final chunk are rejected too (`CliError::SecretstreamTrailingData`'s equivalent),
+ * checked both as more input arrives (`_transform`) and at end-of-stream (`_flush`) so trailing
+ * data appended in the same write as the Final chunk, or arriving in a later write, is caught
+ * either way - not just the case naive testing would think to check first.
+ */
+class SecretStreamDecryptor extends Transform {
+  constructor(key, options) {
+    super(options);
+    this._key = key;
+    this._pullState = null;
+    this._buf = Buffer.alloc(0);
+    this._done = false;
+  }
+
+  _transform(chunk, _encoding, callback) {
+    this._buf = Buffer.concat([this._buf, chunk]);
+    let err;
+    try {
+      this._drain();
+    } catch (e) {
+      err = e;
+    }
+    // See SecretStreamEncryptor._transform's comment - same synchronous-callback pitfall applies.
+    process.nextTick(callback, err);
+  }
+
+  _drain() {
+    if (!this._pullState) {
+      if (this._buf.length < 32) return;
+      const header = this._buf.subarray(0, 32);
+      this._buf = this._buf.subarray(32);
+      this._pullState = new native.SecretStreamPullState(this._key, header);
+    }
+    for (;;) {
+      if (this._done) {
+        if (this._buf.length > 0) {
+          throw new Error('trailing data after the secretstream Final chunk');
+        }
+        return;
+      }
+      if (this._buf.length < 5) return;
+      const tagByte = this._buf[0];
+      const chunkLen = this._buf.readUInt32LE(1);
+      if (chunkLen > CHUNK_BYTES) {
+        throw new Error(`secretstream chunk too large: declared ${chunkLen} bytes, max ${CHUNK_BYTES}`);
+      }
+      const recordLen = 5 + chunkLen + AUTH_TAG_BYTES;
+      if (this._buf.length < recordLen) return;
+      const ciphertext = this._buf.subarray(5, 5 + chunkLen);
+      const authTag = this._buf.subarray(5 + chunkLen, recordLen);
+      this._buf = this._buf.subarray(recordLen);
+      const { tag, plaintext } = this._pullState.pull(tagByte, ciphertext, authTag);
+      this.push(plaintext);
+      if (tag === native.SECRETSTREAM_TAG_FINAL) {
+        this._done = true;
+      }
+    }
+  }
+
+  _flush(callback) {
+    let err;
+    try {
+      if (!this._pullState) {
+        throw new Error('truncated secretstream: missing header');
+      }
+      if (!this._done) {
+        throw new Error('truncated secretstream: stream ended before a Final chunk');
+      }
+      if (this._buf.length > 0) {
+        throw new Error('trailing data after the secretstream Final chunk');
+      }
+    } catch (e) {
+      err = e;
+    }
+    process.nextTick(callback, err);
+  }
+}
+
+module.exports = { SecretStreamEncryptor, SecretStreamDecryptor };

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "dstu-core",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Node.js bindings for dstu-core (Ukrainian DSTU cryptographic standards) - provisional, not yet published to npm",
+  "main": "js/index.js",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/user137/uacrypt"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "js/",
+    "native/index.js",
+    "native/index.d.ts",
+    "native/*.node"
+  ],
+  "napi": {
+    "name": "dstu-core",
+    "triples": {
+      "defaults": false,
+      "additional": [
+        "x86_64-unknown-linux-gnu",
+        "aarch64-apple-darwin",
+        "x86_64-pc-windows-msvc",
+        "aarch64-unknown-linux-gnu"
+      ]
+    }
+  },
+  "license": "MIT OR Apache-2.0",
+  "engines": {
+    "node": ">= 18"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10",
+    "@napi-rs/cli": "^2",
+    "eslint": "^10",
+    "globals": "^17"
+  },
+  "scripts": {
+    "build": "napi build native --platform --release",
+    "build:debug": "napi build native --platform",
+    "test": "node --test",
+    "lint": "eslint .",
+    "prepublishOnly": "napi prepublish -t npm --skip-gh-release"
+  },
+  "optionalDependencies": {
+    "dstu-core-linux-x64-gnu": "0.1.0",
+    "dstu-core-darwin-arm64": "0.1.0",
+    "dstu-core-win32-x64-msvc": "0.1.0",
+    "dstu-core-linux-arm64-gnu": "0.1.0"
+  }
+}