dstu-core 0.3.0 → 0.5.0

package/README.md

@@ -55,12 +55,13 @@ console.log(dstu.secretboxOpen(key, sealed).toString()); // "a message worth pro
 | 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_box` | `boxKeygen`, `boxPublicKey`, `boxSeal`, `boxOpen`, `BoxEncryptor`, `BoxDecryptor` | Public-key encryption (hybrid via KDF over `hazmat::dstu9041`, `l(p)=256`, D-169). `boxSeal`/`boxOpen` hold the whole message in memory; the `stream.Transform` `BoxEncryptor`/`BoxDecryptor` write and read the same bytes (format v3) chunk by chunk, as `uacrypt box-seal`/`box-open` do. `examples/box.js`. |
+| `crypto_box384` | `box384Keygen`, `box384PublicKey`, `box384Seal`, `box384Open`, `Box384Encryptor`, `Box384Decryptor` | `l(p)=384`/E384/1 sibling of `crypto_box` (T-297). `examples/box384.js`. |
+| `crypto_box512` | `box512Keygen`, `box512PublicKey`, `box512Seal`, `box512Open`, `Box512Encryptor`, `Box512Decryptor` | `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_pwhash` | `pwhashHashPassword`, `pwhashVerifyPassword`, `pwhashDeriveKey`, `PWHASH_INTERACTIVE`/`PWHASH_MODERATE`/`PWHASH_SENSITIVE`, `PassphraseEncryptor`, `PassphraseDecryptor` | Argon2id (the one deliberately non-DSTU component, D-49/D-50). `pwhashDeriveKey` equals libsodium's `crypto_pwhash`. `PassphraseEncryptor`/`PassphraseDecryptor` write and read the files `uacrypt encrypt --passphrase` makes (D-219/D-240); each runs Argon2id at 256 MiB once, synchronously on the calling thread like `pwhashHashPassword`. `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`. |

package/js/index.js

@@ -15,10 +15,9 @@
  */
 
 const native = require('../native/index.js');
-const { SecretStreamEncryptor, SecretStreamDecryptor } = require('./secretstream.js');
+const streams = require('./secretstream.js');
 
 module.exports = {
   ...native,
-  SecretStreamEncryptor,
-  SecretStreamDecryptor,
+  ...streams,
 };

package/js/secretstream.js

@@ -2,9 +2,10 @@
 
 /**
  * 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
+ * T-50 step 3) - hides chunk/tag/length-prefix bookkeeping behind a `stream.Transform` pair. The
+ * framing itself (record layout, length rules, Final, trailing data) is dstu-core's stream-file
+ * codec, exposed as SecretStreamFileEncryptor/SecretStreamFileDecryptor (T-284); this module only
+ * buffers. Mirrors
  * bindings/python/python/dstu_core/secretstream.py's own design exactly (see D-118's two
  * standing pitfalls this port re-checks below).
  *
@@ -19,12 +20,9 @@
 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.
+// dstu-core's crypto_secretstream::CHUNK_BYTES (D-208): the codec seals and checks it; this module
+// only needs it to cut input into chunks.
 const CHUNK_BYTES = 8 * 1024;
-const AUTH_TAG_BYTES = 16;
-// Matches dstu-core's crypto_secretstream::FORMAT_VERSION (D-208); the shared vectors pin it.
-const FORMAT_VERSION = 2;
 
 /**
  * Write-only Transform: buffers input and pushes each full 8 KiB chunk downstream as it fills,
@@ -44,27 +42,28 @@ const FORMAT_VERSION = 2;
 class SecretStreamEncryptor extends Transform {
   constructor(key, options) {
     super(options);
-    this._pushState = new native.SecretStreamPushState(key);
+    this._enc = this._startCodec(key);
     this._buf = Buffer.alloc(0);
-    this.push(Buffer.concat([Buffer.from([FORMAT_VERSION]), this._pushState.header]));
+    this.push(this._enc.prefix);
   }
 
-  _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]));
+  /** The native codec for `key`; the box/passphrase subclasses start it their own way. */
+  _startCodec(key) {
+    return new native.SecretStreamFileEncryptor(key);
   }
 
   _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);
+      // Hold back the last chunk (even a full one) until _flush: only then is it known to be the
+      // Final one (an exact multiple of 8 KiB ends in a full Final record, D-208).
+      let pos = 0;
+      while (this._buf.length - pos > CHUNK_BYTES) {
+        this.push(this._enc.sealChunk(this._buf.subarray(pos, pos + CHUNK_BYTES)));
+        pos += CHUNK_BYTES;
       }
+      this._buf = this._buf.subarray(pos);
     } catch (e) {
       err = e;
     }
@@ -79,7 +78,7 @@ class SecretStreamEncryptor extends Transform {
   _flush(callback) {
     let err;
     try {
-      this._pushChunk(native.SECRETSTREAM_TAG_FINAL, this._buf);
+      this.push(this._enc.sealFinal(this._buf));
       this._buf = Buffer.alloc(0);
     } catch (e) {
       err = e;
@@ -94,29 +93,42 @@ class SecretStreamEncryptor extends Transform {
  * 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.
+ * D-118 pitfall check #2: the untrusted length field, the 8 KiB rule, trailing data after Final
+ * and truncation are all the codec's checks (T-284); this class only collects `nextLen()` bytes
+ * at a time. A Final chunk's plaintext is pushed only in `_flush`, once the input is known to end
+ * right after it.
  */
 class SecretStreamDecryptor extends Transform {
   constructor(key, options) {
     super(options);
-    this._key = key;
-    this._pullState = null;
+    this._dec = this._startCodec(key);
     this._buf = Buffer.alloc(0);
-    this._done = false;
+  }
+
+  /** The native codec for `key`, or null while a subclass still collects its prefix. */
+  _startCodec(key) {
+    return new native.SecretStreamFileDecryptor(key);
   }
 
   _transform(chunk, _encoding, callback) {
     this._buf = Buffer.concat([this._buf, chunk]);
     let err;
     try {
-      this._drain();
+      if (this._dec === null) {
+        if (this._buf.length < this._prefixBytes) {
+          process.nextTick(callback);
+          return;
+        }
+        this._dec = this._openPrefixed(this._buf.subarray(0, this._prefixBytes));
+        this._buf = this._buf.subarray(this._prefixBytes);
+      }
+      let pos = 0;
+      for (let want = this._dec.nextLen(); this._buf.length - pos >= want; want = this._dec.nextLen()) {
+        const plaintext = this._dec.feed(this._buf.subarray(pos, pos + want));
+        pos += want;
+        if (plaintext.length > 0) this.push(plaintext);
+      }
+      this._buf = this._buf.subarray(pos);
     } catch (e) {
       err = e;
     }
@@ -124,57 +136,12 @@ class SecretStreamDecryptor extends Transform {
     process.nextTick(callback, err);
   }
 
-  _drain() {
-    if (!this._pullState) {
-      if (this._buf.length >= 1 && this._buf[0] !== FORMAT_VERSION) {
-        throw new Error(`unsupported stream format version ${this._buf[0]} (this build reads ${FORMAT_VERSION})`);
-      }
-      if (this._buf.length < 33) return;
-      const header = this._buf.subarray(1, 33);
-      this._buf = this._buf.subarray(33);
-      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}`);
-      }
-      if (tagByte !== native.SECRETSTREAM_TAG_FINAL && chunkLen !== CHUNK_BYTES) {
-        throw new Error(`non-final chunk of ${chunkLen} bytes, must be exactly ${CHUNK_BYTES} (D-208)`);
-      }
-      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');
-      }
+      if (this._dec === null) throw new Error(`input too short to contain a ${this._prefixName}`);
+      const plaintext = this._dec.finish();
+      if (plaintext.length > 0) this.push(plaintext);
     } catch (e) {
       err = e;
     }
@@ -182,4 +149,130 @@ class SecretStreamDecryptor extends Transform {
   }
 }
 
-module.exports = { SecretStreamEncryptor, SecretStreamDecryptor };
+function checkLength(buf, bytes, name) {
+  if (!Buffer.isBuffer(buf) || buf.length !== bytes) {
+    throw new TypeError(`${name} must be a ${bytes}-byte Buffer`);
+  }
+}
+
+/**
+ * `crypto_box` sealed to `publicKey` as a stream (format v3, T-265/T-269): the same bytes
+ * `boxSeal` returns, written chunk by chunk; `boxOpen`/`BoxDecryptor` read them.
+ */
+class BoxEncryptor extends SecretStreamEncryptor {
+  _startCodec(publicKey) {
+    return native.SecretStreamFileEncryptor.boxSeal(publicKey);
+  }
+}
+
+/** `crypto_box384` counterpart of `BoxEncryptor`. */
+class Box384Encryptor extends SecretStreamEncryptor {
+  _startCodec(publicKey) {
+    return native.SecretStreamFileEncryptor.box384Seal(publicKey);
+  }
+}
+
+/** `crypto_box512` counterpart of `BoxEncryptor`. */
+class Box512Encryptor extends SecretStreamEncryptor {
+  _startCodec(publicKey) {
+    return native.SecretStreamFileEncryptor.box512Seal(publicKey);
+  }
+}
+
+/**
+ * A passphrase file (D-219/D-240) - the bytes `uacrypt encrypt --passphrase` writes. The
+ * constructor runs Argon2id (256 MiB, t=3, about a second) on the calling thread.
+ */
+class PassphraseEncryptor extends SecretStreamEncryptor {
+  _startCodec(passphrase) {
+    return native.SecretStreamFileEncryptor.passphraseSeal(passphrase);
+  }
+}
+
+/**
+ * Collects the bytes in front of the stream file, then opens the codec with them. The secret is
+ * held only until then.
+ */
+class PrefixedDecryptor extends SecretStreamDecryptor {
+  _startCodec(secret) {
+    this._secret = secret;
+    return null;
+  }
+
+  _openPrefixed(prefix) {
+    const dec = this._openCodec(this._secret, prefix);
+    this._secret = null;
+    return dec;
+  }
+}
+
+/** Reads a `crypto_box` stream (or a `boxSeal` blob) with bounded memory. */
+class BoxDecryptor extends PrefixedDecryptor {
+  constructor(secretKey, options) {
+    checkLength(secretKey, 32, 'secretKey');
+    super(secretKey, options);
+    this._prefixBytes = native.BOX_OPEN_STREAM_PREFIX_BYTES;
+    this._prefixName = 'sealed message';
+  }
+
+  _openCodec(secretKey, prefix) {
+    return native.SecretStreamFileDecryptor.boxOpen(secretKey, prefix);
+  }
+}
+
+/** `crypto_box384` counterpart of `BoxDecryptor`. */
+class Box384Decryptor extends PrefixedDecryptor {
+  constructor(secretKey, options) {
+    checkLength(secretKey, 48, 'secretKey');
+    super(secretKey, options);
+    this._prefixBytes = native.BOX384_OPEN_STREAM_PREFIX_BYTES;
+    this._prefixName = 'sealed message';
+  }
+
+  _openCodec(secretKey, prefix) {
+    return native.SecretStreamFileDecryptor.box384Open(secretKey, prefix);
+  }
+}
+
+/** `crypto_box512` counterpart of `BoxDecryptor`. */
+class Box512Decryptor extends PrefixedDecryptor {
+  constructor(secretKey, options) {
+    checkLength(secretKey, 64, 'secretKey');
+    super(secretKey, options);
+    this._prefixBytes = native.BOX512_OPEN_STREAM_PREFIX_BYTES;
+    this._prefixName = 'sealed message';
+  }
+
+  _openCodec(secretKey, prefix) {
+    return native.SecretStreamFileDecryptor.box512Open(secretKey, prefix);
+  }
+}
+
+/**
+ * Reads a passphrase file. The header is checked before Argon2 runs (on the calling thread, once
+ * the header has arrived); a wrong passphrase errors at the first record.
+ */
+class PassphraseDecryptor extends PrefixedDecryptor {
+  constructor(passphrase, options) {
+    super(passphrase, options);
+    this._prefixBytes = native.PASSPHRASE_FILE_HEADER_BYTES;
+    this._prefixName = 'passphrase file header';
+  }
+
+  _openCodec(passphrase, header) {
+    return native.SecretStreamFileDecryptor.passphraseOpen(header, passphrase);
+  }
+}
+
+module.exports = {
+  SecretStreamEncryptor,
+  SecretStreamDecryptor,
+  BoxEncryptor,
+  BoxDecryptor,
+  Box384Encryptor,
+  Box384Decryptor,
+  Box512Encryptor,
+  Box512Decryptor,
+  PassphraseEncryptor,
+  PassphraseDecryptor,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dstu-core",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "private": false,
   "description": "Node.js bindings for dstu-core (Ukrainian DSTU cryptographic standards)",
   "main": "js/index.js",
@@ -47,9 +47,9 @@
     "prepublishOnly": "napi prepublish -t npm --skip-gh-release"
   },
   "optionalDependencies": {
-    "dstu-core-linux-x64-gnu": "0.3.0",
-    "dstu-core-darwin-arm64": "0.3.0",
-    "dstu-core-win32-x64-msvc": "0.3.0",
-    "dstu-core-linux-arm64-gnu": "0.3.0"
+    "dstu-core-linux-x64-gnu": "0.5.0",
+    "dstu-core-darwin-arm64": "0.5.0",
+    "dstu-core-win32-x64-msvc": "0.5.0",
+    "dstu-core-linux-arm64-gnu": "0.5.0"
   }
 }