castrum 0.9.3 → 0.9.6

package/rust/crypto/aead.rs

@@ -0,0 +1,378 @@
+// rust/crypto/aead.rs — authenticated encryption (AES-256-GCM, ChaCha20-Poly1305).
+//
+// Backend-framework feature: symmetric encryption for cookies / session
+// payloads / at-rest secrets. Uses aws-lc-rs's `aead` module (already a
+// dependency for HMAC-SHA256), so no new crate is pulled in. Nonce and plaintext
+// lengths are validated; a 12-byte nonce is required (both algorithms use the
+// same 96-bit nonce length).
+//
+// Pure-Rust core (no napi types) stays unit-testable; only the entry points
+// use napi types.
+
+use aws_lc_rs::aead::{self, Aad, LessSafeKey, Nonce, UnboundKey};
+use aws_lc_rs::error::Unspecified;
+use napi::bindgen_prelude::*;
+use napi_derive::napi;
+
+const NONCE_LEN: usize = 12;
+
+/// Derive a unique per-item nonce for the batch APIs.
+///
+/// AES-GCM and ChaCha20-Poly1305 are catastrophic under nonce reuse with the
+/// same key. The batch APIs accept ONE caller-provided base nonce; this derives
+/// a distinct nonce per item by XOR-ing the item index into the low 8 bytes.
+///
+/// SAFETY CONTRACT: callers MUST use a fresh base nonce for every batch call
+/// (never reuse a base nonce with the same key across calls), otherwise item `i`
+/// of two different batches share a nonce and keystream/tag reuse applies.
+#[inline]
+fn batch_nonce(base: &[u8], index: usize) -> [u8; NONCE_LEN] {
+    let mut nonce = [0u8; NONCE_LEN];
+    nonce.copy_from_slice(base);
+    let idx = (index as u64).to_be_bytes();
+    for (slot, byte) in nonce[4..].iter_mut().zip(idx.iter()) {
+        *slot ^= byte;
+    }
+    nonce
+}
+
+fn resolve_algorithm(name: Option<&str>) -> Result<&'static aead::Algorithm> {
+    match name {
+        None | Some("aes-256-gcm") => Ok(&aead::AES_256_GCM),
+        Some("chacha20-poly1305") => Ok(&aead::CHACHA20_POLY1305),
+        Some(other) => Err(Error::from_reason(format!(
+            "unsupported aead algorithm: {other} (expected aes-256-gcm | chacha20-poly1305)"
+        ))),
+    }
+}
+
+// ── Pure-Rust core ─────────────────────────────────────────────
+
+/// Encrypt `plaintext`, appending the 16-byte auth tag. Returns the ciphertext
+/// (plaintext length + tag).
+pub fn encrypt(
+    alg: &'static aead::Algorithm,
+    key: &[u8],
+    nonce: &[u8],
+    plaintext: &[u8],
+) -> std::result::Result<Vec<u8>, Unspecified> {
+    let unbound = UnboundKey::new(alg, key)?;
+    let sealing = LessSafeKey::new(unbound);
+    encrypt_with_key(&sealing, nonce, plaintext)
+}
+
+/// Encrypt with a PRE-COMPILED key (no per-call `UnboundKey`/`LessSafeKey`
+/// derivation — the win the `AeadCipher` instance exploits).
+pub fn encrypt_with_key(
+    sealing: &LessSafeKey,
+    nonce: &[u8],
+    plaintext: &[u8],
+) -> std::result::Result<Vec<u8>, Unspecified> {
+    if nonce.len() != NONCE_LEN {
+        return Err(Unspecified);
+    }
+    let mut nonce_arr = [0u8; NONCE_LEN];
+    nonce_arr.copy_from_slice(nonce);
+    let nonce = Nonce::assume_unique_for_key(nonce_arr);
+    let mut in_out = plaintext.to_vec();
+    sealing.seal_in_place_append_tag(nonce, Aad::empty(), &mut in_out)?;
+    Ok(in_out)
+}
+
+/// Decrypt `ciphertext` (ciphertext + tag), returning the plaintext.
+pub fn decrypt(
+    alg: &'static aead::Algorithm,
+    key: &[u8],
+    nonce: &[u8],
+    ciphertext: &[u8],
+) -> std::result::Result<Vec<u8>, Unspecified> {
+    let unbound = UnboundKey::new(alg, key)?;
+    let opening = LessSafeKey::new(unbound);
+    decrypt_with_key(&opening, nonce, ciphertext)
+}
+
+/// Decrypt with a PRE-COMPILED key (no per-call key derivation).
+pub fn decrypt_with_key(
+    opening: &LessSafeKey,
+    nonce: &[u8],
+    ciphertext: &[u8],
+) -> std::result::Result<Vec<u8>, Unspecified> {
+    if nonce.len() != NONCE_LEN {
+        return Err(Unspecified);
+    }
+    let mut nonce_arr = [0u8; NONCE_LEN];
+    nonce_arr.copy_from_slice(nonce);
+    let nonce = Nonce::assume_unique_for_key(nonce_arr);
+    // Single copy: borrow the ciphertext in, then truncate in place to the
+    // plaintext length (the tag occupies the trailing bytes) and return it.
+    let mut in_out = ciphertext.to_vec();
+    let opened = opening.open_in_place(nonce, Aad::empty(), &mut in_out)?;
+    let plaintext_len = opened.len();
+    in_out.truncate(plaintext_len);
+    Ok(in_out)
+}
+
+// ── NAPI entry points ──────────────────────────────────────────
+
+/// Encrypt `plaintext` → ciphertext+tag. `key` must be 32 bytes; `nonce` must
+/// be 12 bytes. Defaults to AES-256-GCM; pass `"chacha20-poly1305"` to switch.
+#[napi]
+pub fn aead_encrypt(
+    key: Uint8Array,
+    nonce: Uint8Array,
+    plaintext: Uint8Array,
+    algorithm: Option<String>,
+) -> Result<Buffer> {
+    let alg = resolve_algorithm(algorithm.as_deref())?;
+    encrypt(alg, key.as_ref(), nonce.as_ref(), plaintext.as_ref())
+        .map(Buffer::from)
+        .map_err(|e| Error::from_reason(format!("aead encrypt failed: {e:?}")))
+}
+
+/// Decrypt `ciphertext`+tag → plaintext. Returns `null` when the tag fails to
+/// authenticate (tampered / wrong key) or the inputs are malformed.
+#[napi]
+pub fn aead_decrypt(
+    key: Uint8Array,
+    nonce: Uint8Array,
+    ciphertext: Uint8Array,
+    algorithm: Option<String>,
+) -> Result<Option<Buffer>> {
+    let alg = resolve_algorithm(algorithm.as_deref())?;
+    match decrypt(alg, key.as_ref(), nonce.as_ref(), ciphertext.as_ref()) {
+        Ok(pt) => Ok(Some(Buffer::from(pt))),
+        Err(_) => Ok(None),
+    }
+}
+
+/// Higher-order instance: precompiles the algorithm + key into a `LessSafeKey`
+/// once at construction, so `encrypt`/`decrypt` never re-derive the key on the
+/// per-call path.
+#[napi]
+pub struct AeadCipher {
+    key: LessSafeKey,
+}
+
+#[napi]
+impl AeadCipher {
+    #[napi(constructor)]
+    pub fn new(key: Uint8Array, algorithm: Option<String>) -> Result<Self> {
+        let alg = resolve_algorithm(algorithm.as_deref())?;
+        let unbound = UnboundKey::new(alg, key.as_ref())
+            .map_err(|e| Error::from_reason(format!("invalid aead key: {e:?}")))?;
+        Ok(Self {
+            key: LessSafeKey::new(unbound),
+        })
+    }
+
+    /// Encrypt `plaintext` → ciphertext+tag with the precompiled key.
+    #[napi]
+    pub fn encrypt(&self, nonce: Uint8Array, plaintext: Uint8Array) -> Result<Buffer> {
+        encrypt_with_key(&self.key, nonce.as_ref(), plaintext.as_ref())
+            .map(Buffer::from)
+            .map_err(|e| Error::from_reason(format!("aead encrypt failed: {e:?}")))
+    }
+
+    /// Decrypt `ciphertext`+tag → plaintext, or `null` on auth failure.
+    #[napi]
+    pub fn decrypt(&self, nonce: Uint8Array, ciphertext: Uint8Array) -> Result<Option<Buffer>> {
+        match decrypt_with_key(&self.key, nonce.as_ref(), ciphertext.as_ref()) {
+            Ok(pt) => Ok(Some(Buffer::from(pt))),
+            Err(_) => Ok(None),
+        }
+    }
+}
+
+/// Parallel encrypt batch: packed `[u32 count]{[u32 len][plaintext]}` in →
+/// packed `[u32 count]{[u32 len][ciphertext+tag]}` out.
+///
+/// SECURITY: a unique nonce is derived per item from the caller-provided base
+/// `nonce` (item index XOR-ed into the low 8 bytes). The base nonce MUST be
+/// fresh for every batch call — never reuse a base nonce with the same key.
+#[napi]
+pub fn aead_encrypt_batch_packed(
+    data: Uint8Array,
+    key: Uint8Array,
+    nonce: Uint8Array,
+    algorithm: Option<String>,
+) -> Result<Buffer> {
+    let alg = resolve_algorithm(algorithm.as_deref())?;
+
+    let enc_for = |plaintext: &[u8], index: usize| -> Vec<u8> {
+        let n = batch_nonce(nonce.as_ref(), index);
+        encrypt(alg, key.as_ref(), &n, plaintext).unwrap_or_default()
+    };
+
+    crate::util::run_packed_batch_idx(data.as_ref(), enc_for).map(Buffer::from)
+}
+
+/// Parallel decrypt batch: packed ciphertexts in → packed plaintexts out.
+/// Items whose tag fails to authenticate produce an empty (zero-length) entry.
+///
+/// SECURITY: the SAME per-item nonce derivation as
+/// {@link aead_encrypt_batch_packed} must be used — pass the same base `nonce`
+/// and batch ordering to decrypt what was encrypted.
+#[napi]
+pub fn aead_decrypt_batch_packed(
+    data: Uint8Array,
+    key: Uint8Array,
+    nonce: Uint8Array,
+    algorithm: Option<String>,
+) -> Result<Buffer> {
+    let alg = resolve_algorithm(algorithm.as_deref())?;
+
+    let dec_for = |ciphertext: &[u8], index: usize| -> Vec<u8> {
+        let n = batch_nonce(nonce.as_ref(), index);
+        decrypt(alg, key.as_ref(), &n, ciphertext).unwrap_or_default()
+    };
+
+    crate::util::run_packed_batch_idx(data.as_ref(), dec_for).map(Buffer::from)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn key_bytes() -> [u8; 32] {
+        [7u8; 32]
+    }
+
+    fn nonce_bytes() -> [u8; 12] {
+        [3u8; 12]
+    }
+
+    #[test]
+    fn aes256gcm_roundtrip() {
+        let pt = b"secret session payload";
+        let ct = encrypt(&aead::AES_256_GCM, &key_bytes(), &nonce_bytes(), pt).unwrap();
+        assert_eq!(ct.len(), pt.len() + 16);
+        let dec = decrypt(&aead::AES_256_GCM, &key_bytes(), &nonce_bytes(), &ct).unwrap();
+        assert_eq!(dec, pt);
+    }
+
+    #[test]
+    fn aead_cipher_instance_roundtrips_and_rejects() {
+        // Precompiled-key instance: encrypt/decrypt with no per-call key
+        // derivation. Must match the scalar core exactly.
+        let cipher = AeadCipher::new(Uint8Array::new(key_bytes().to_vec()), None).unwrap();
+        let pt = b"session cookie value";
+
+        let ct = cipher
+            .encrypt(
+                Uint8Array::new(nonce_bytes().to_vec()),
+                Uint8Array::new(pt.to_vec()),
+            )
+            .unwrap();
+        assert_eq!(ct.len(), pt.len() + 16);
+
+        let ct_bytes = ct.to_vec();
+        let dec = cipher
+            .decrypt(
+                Uint8Array::new(nonce_bytes().to_vec()),
+                Uint8Array::new(ct_bytes.clone()),
+            )
+            .unwrap();
+        assert_eq!(&dec.unwrap()[..], pt);
+
+        // Wrong-key instance fails to authenticate.
+        let other = AeadCipher::new(Uint8Array::new([9u8; 32].to_vec()), None).unwrap();
+        assert!(other
+            .decrypt(
+                Uint8Array::new(nonce_bytes().to_vec()),
+                Uint8Array::new(ct_bytes)
+            )
+            .unwrap()
+            .is_none());
+
+        // Malformed nonce length → error.
+        assert!(cipher
+            .encrypt(Uint8Array::new(vec![0u8; 8]), Uint8Array::new(pt.to_vec()))
+            .is_err());
+
+        // Unsupported algorithm → construction error.
+        assert!(AeadCipher::new(
+            Uint8Array::new(key_bytes().to_vec()),
+            Some("aes-128-gcm".to_string())
+        )
+        .is_err());
+    }
+
+    #[test]
+    fn batch_nonce_unique_per_item() {
+        // Regression: the batch APIs must NEVER reuse a nonce across items.
+        let base = nonce_bytes();
+        let n0 = batch_nonce(&base, 0);
+        let n1 = batch_nonce(&base, 1);
+        let n2 = batch_nonce(&base, 2);
+        assert_ne!(n0, n1, "nonce for item 0 and 1 must differ");
+        assert_ne!(n1, n2, "nonce for item 1 and 2 must differ");
+        assert_ne!(n0, n2);
+        // Uniqueness for a full large batch too.
+        let mut seen = std::collections::HashSet::new();
+        for i in 0..1024 {
+            assert!(
+                seen.insert(batch_nonce(&base, i)),
+                "nonce reused at item {i}"
+            );
+        }
+    }
+
+    #[test]
+    fn batch_nonce_derived_encrypt_roundtrip() {
+        // Each item encrypted with its derived nonce decrypts correctly, and a
+        // mismatched nonce fails to authenticate (catches nonce-reuse misuse).
+        let alg = &aead::AES_256_GCM;
+        let key = key_bytes();
+        let base = nonce_bytes();
+
+        let p0 = b"first payload";
+        let p1 = b"second payload";
+
+        let c0 = encrypt(alg, &key, &batch_nonce(&base, 0), p0).unwrap();
+        let c1 = encrypt(alg, &key, &batch_nonce(&base, 1), p1).unwrap();
+
+        assert_eq!(decrypt(alg, &key, &batch_nonce(&base, 0), &c0).unwrap(), p0);
+        assert_eq!(decrypt(alg, &key, &batch_nonce(&base, 1), &c1).unwrap(), p1);
+        // Cross-nonce decryption must fail authentication.
+        assert!(decrypt(alg, &key, &batch_nonce(&base, 1), &c0).is_err());
+        assert!(decrypt(alg, &key, &batch_nonce(&base, 0), &c1).is_err());
+    }
+
+    #[test]
+    fn chacha20_roundtrip() {
+        let pt = b"another payload";
+        let ct = encrypt(&aead::CHACHA20_POLY1305, &key_bytes(), &nonce_bytes(), pt).unwrap();
+        let dec = decrypt(&aead::CHACHA20_POLY1305, &key_bytes(), &nonce_bytes(), &ct).unwrap();
+        assert_eq!(dec, pt);
+    }
+
+    #[test]
+    fn tampered_ciphertext_fails_auth() {
+        let pt = b"integrity matters";
+        let mut ct = encrypt(&aead::AES_256_GCM, &key_bytes(), &nonce_bytes(), pt).unwrap();
+        ct[0] ^= 0xff;
+        assert!(decrypt(&aead::AES_256_GCM, &key_bytes(), &nonce_bytes(), &ct).is_err());
+    }
+
+    #[test]
+    fn wrong_key_fails_auth() {
+        let pt = b"integrity matters";
+        let ct = encrypt(&aead::AES_256_GCM, &key_bytes(), &nonce_bytes(), pt).unwrap();
+        let wrong_key = [9u8; 32];
+        assert!(decrypt(&aead::AES_256_GCM, &wrong_key, &nonce_bytes(), &ct).is_err());
+    }
+
+    #[test]
+    fn wrong_nonce_fails_auth() {
+        let pt = b"integrity matters";
+        let ct = encrypt(&aead::AES_256_GCM, &key_bytes(), &nonce_bytes(), pt).unwrap();
+        let wrong_nonce = [4u8; 12];
+        assert!(decrypt(&aead::AES_256_GCM, &key_bytes(), &wrong_nonce, &ct).is_err());
+    }
+
+    #[test]
+    fn rejects_bad_nonce_length() {
+        assert!(encrypt(&aead::AES_256_GCM, &key_bytes(), &[0u8; 8], b"x").is_err());
+        assert!(decrypt(&aead::AES_256_GCM, &key_bytes(), &[0u8; 8], b"x").is_err());
+    }
+}

package/rust/crypto/argon2.rs

@@ -0,0 +1,265 @@
+// rust/crypto/argon2.rs — argon2id password hashing.
+//
+// Backend-framework feature: password storage hashing. argon2id is the OWASP
+// recommendation for new hashes; it is deliberately CPU/memory-heavy, which
+// makes it an ideal candidate to offload to Rust (and parallelize with rayon).
+// The `argon2` crate (RustCrypto) is pure Rust; `SaltString::encode_b64` lets us
+// feed a caller-supplied salt so outputs are deterministic (unit-testable).
+//
+// Pure-Rust core (no napi types) stays unit-testable; only the entry points
+// use napi types.
+
+use argon2::password_hash::{PasswordHash, PasswordHasher, PasswordVerifier, SaltString};
+use argon2::{Algorithm, Argon2, Params, Version};
+use napi::bindgen_prelude::*;
+use napi_derive::napi;
+
+// ── Options ────────────────────────────────────────────────────
+
+/// argon2id parameters (defaults follow OWASP: 19 MiB, 2 iterations, 1 lane,
+/// 32-byte output). Callers may lower the memory cost for fast benchmarks.
+#[napi(object)]
+pub struct PasswordHashOptions {
+    /// Memory cost in KiB (m). Default: 19_456 (19 MiB).
+    pub m_cost: Option<u32>,
+    /// Iterations (t). Default: 2.
+    pub t_cost: Option<u32>,
+    /// Parallelism (p). Default: 1.
+    pub p_cost: Option<u32>,
+    /// Output length in bytes. Default: 32.
+    pub out_len: Option<u32>,
+}
+
+fn resolve_opts(o: Option<&PasswordHashOptions>) -> (u32, u32, u32, u32) {
+    match o {
+        Some(o) => (
+            o.m_cost.unwrap_or(19_456),
+            o.t_cost.unwrap_or(2),
+            o.p_cost.unwrap_or(1),
+            o.out_len.unwrap_or(32),
+        ),
+        None => (19_456, 2, 1, 32),
+    }
+}
+
+// ── Pure-Rust core ─────────────────────────────────────────────
+
+/// Hash `password` with argon2id using the given raw salt bytes. Returns the
+/// PHC string (`$argon2id$v=19$m=...,t=...,p=...$<b64 salt>$<b64 hash>`).
+pub fn hash_password(
+    password: &[u8],
+    salt: &[u8],
+    m_cost: u32,
+    t_cost: u32,
+    p_cost: u32,
+    out_len: u32,
+) -> std::result::Result<String, argon2::password_hash::Error> {
+    let params = Params::new(m_cost, t_cost, p_cost, Some(out_len as usize))?;
+    let argon2 = Argon2::new(Algorithm::Argon2id, Version::V0x13, params);
+    let salt = SaltString::encode_b64(salt)?;
+    Ok(argon2.hash_password(password, &salt)?.to_string())
+}
+
+/// Verify a password against a PHC string (constant-time internally).
+pub fn verify_password(password: &[u8], phc: &[u8]) -> bool {
+    let Ok(phc_str) = std::str::from_utf8(phc) else {
+        return false;
+    };
+    let Ok(parsed) = PasswordHash::new(phc_str) else {
+        return false;
+    };
+    Argon2::default().verify_password(password, &parsed).is_ok()
+}
+
+// ── NAPI entry points ──────────────────────────────────────────
+
+/// Hash a password with argon2id. `salt` must be at least 8 bytes; output is a
+/// PHC string. Deterministic given the same inputs.
+#[napi]
+pub fn password_hash(
+    password: Uint8Array,
+    salt: Uint8Array,
+    options: Option<PasswordHashOptions>,
+) -> Result<Buffer> {
+    let (m, t, p, out_len) = resolve_opts(options.as_ref());
+    let phc = hash_password(password.as_ref(), salt.as_ref(), m, t, p, out_len)
+        .map_err(|e| Error::from_reason(format!("argon2 hash failed: {e}")))?;
+    Ok(Buffer::from(phc.into_bytes()))
+}
+
+/// Verify a password against a PHC string. Returns false on any parse failure.
+#[napi]
+pub fn password_verify(password: Uint8Array, phc: Buffer) -> bool {
+    verify_password(password.as_ref(), phc.as_ref())
+}
+
+/// Packed password-verify batch (two packed lists: passwords + PHC strings,
+/// zipped) → bitset of valid. Items with malformed PHC strings yield `false`.
+#[napi]
+pub fn password_verify_batch_packed(passwords: Uint8Array, phcs: Uint8Array) -> Result<Buffer> {
+    use crate::util::packed::PackedIter;
+    let pws = passwords.as_ref();
+    let ph = phcs.as_ref();
+    let count = PackedIter::new(pws)?.len().min(PackedIter::new(ph)?.len());
+    let mut out = Vec::with_capacity(4 + count.div_ceil(8));
+    out.extend_from_slice(&(count as u32).to_le_bytes());
+    out.resize(4 + count.div_ceil(8), 0);
+    for (i, (pw, phc)) in PackedIter::new(pws)?.zip(PackedIter::new(ph)?).enumerate() {
+        if verify_password(pw, phc) {
+            out[4 + (i >> 3)] |= 1 << (i & 7);
+        }
+    }
+    Ok(Buffer::from(out))
+}
+
+/// Higher-order instance: precompiles the argon2id `Params`/`Argon2` once at
+/// construction (fixed m/t/p/out_len), so every `hash` skips the per-call
+/// parameter construction — the CPU/memory cost of the hash itself is
+/// unchanged, only the setup is amortized.
+#[napi]
+pub struct Argon2Hasher {
+    argon2: Argon2<'static>,
+}
+
+#[napi]
+impl Argon2Hasher {
+    #[napi(constructor)]
+    pub fn new(options: Option<PasswordHashOptions>) -> Result<Self> {
+        let (m, t, p, out_len) = resolve_opts(options.as_ref());
+        let params = Params::new(m, t, p, Some(out_len as usize))
+            .map_err(|e| Error::from_reason(format!("invalid argon2 params: {e}")))?;
+        Ok(Self {
+            argon2: Argon2::new(Algorithm::Argon2id, Version::V0x13, params),
+        })
+    }
+
+    /// Hash a password with the precompiled params → PHC string bytes.
+    #[napi]
+    pub fn hash(&self, password: Uint8Array, salt: Uint8Array) -> Result<Buffer> {
+        let salt = SaltString::encode_b64(salt.as_ref())
+            .map_err(|e| Error::from_reason(format!("invalid salt: {e}")))?;
+        let phc = self
+            .argon2
+            .hash_password(password.as_ref(), &salt)
+            .map_err(|e| Error::from_reason(format!("argon2 hash failed: {e}")))?;
+        Ok(Buffer::from(phc.to_string().into_bytes()))
+    }
+
+    /// Verify a password against a PHC string. Returns false on any failure.
+    #[napi]
+    pub fn verify(&self, password: Uint8Array, phc: Buffer) -> bool {
+        verify_password(password.as_ref(), phc.as_ref())
+    }
+}
+
+/// Parallel argon2id batch: packed `[u32 count]{[u32 len][password]}` in →
+/// packed `[u32 count]{[u32 len][phc]}` out, all hashed with the SAME salt.
+#[napi]
+pub fn password_hash_batch_packed(
+    data: Uint8Array,
+    salt: Uint8Array,
+    options: Option<PasswordHashOptions>,
+) -> Result<Buffer> {
+    let (m, t, p, out_len) = resolve_opts(options.as_ref());
+
+    let phc_for = |password: &[u8]| -> Vec<u8> {
+        hash_password(password, salt.as_ref(), m, t, p, out_len)
+            .map(|s| s.into_bytes())
+            .unwrap_or_default()
+    };
+
+    crate::util::run_packed_batch(data.as_ref(), phc_for).map(Buffer::from)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    const PASSWORD: &[u8] = b"correct horse battery staple";
+    const SALT: &[u8] = b"0123456789abcdef";
+
+    #[test]
+    fn hash_then_verify_roundtrip() {
+        let phc = hash_password(PASSWORD, SALT, 4096, 2, 1, 32).unwrap();
+        assert!(phc.starts_with("$argon2id$v=19$"));
+        assert!(verify_password(PASSWORD, phc.as_bytes()));
+    }
+
+    #[test]
+    fn argon2_hasher_instance_roundtrips() {
+        // Precompiled-params instance: hash/verify with no per-call Params
+        // construction. Output must match the scalar core for the same params.
+        let hasher = Argon2Hasher::new(Some(PasswordHashOptions {
+            m_cost: Some(4096),
+            t_cost: Some(2),
+            p_cost: Some(1),
+            out_len: Some(32),
+        }))
+        .unwrap();
+
+        let phc = hasher
+            .hash(
+                Uint8Array::new(PASSWORD.to_vec()),
+                Uint8Array::new(SALT.to_vec()),
+            )
+            .unwrap();
+        let phc_str = String::from_utf8(phc.to_vec()).unwrap();
+        assert!(phc_str.starts_with("$argon2id$v=19$"));
+
+        // The instance output matches the scalar core byte-for-byte.
+        let scalar = hash_password(PASSWORD, SALT, 4096, 2, 1, 32).unwrap();
+        assert_eq!(phc_str, scalar);
+
+        // Verify: correct password true, wrong password false.
+        assert!(hasher.verify(
+            Uint8Array::new(PASSWORD.to_vec()),
+            Buffer::from(phc_str.clone().into_bytes())
+        ));
+        assert!(!hasher.verify(
+            Uint8Array::new(b"wrong-password".to_vec()),
+            Buffer::from(phc_str.into_bytes())
+        ));
+
+        // Invalid options → construction error.
+        assert!(Argon2Hasher::new(Some(PasswordHashOptions {
+            m_cost: Some(0),
+            t_cost: Some(2),
+            p_cost: Some(1),
+            out_len: Some(32),
+        }))
+        .is_err());
+    }
+
+    #[test]
+    fn verify_rejects_wrong_password() {
+        let phc = hash_password(PASSWORD, SALT, 4096, 2, 1, 32).unwrap();
+        assert!(!verify_password(b"wrong password", phc.as_bytes()));
+    }
+
+    #[test]
+    fn verify_is_deterministic_given_salt() {
+        let a = hash_password(PASSWORD, SALT, 4096, 2, 1, 32).unwrap();
+        let b = hash_password(PASSWORD, SALT, 4096, 2, 1, 32).unwrap();
+        assert_eq!(a, b);
+    }
+
+    #[test]
+    fn different_salt_different_hash() {
+        let a = hash_password(PASSWORD, b"aaaaaaaaaaaaaaaa", 4096, 2, 1, 32).unwrap();
+        let b = hash_password(PASSWORD, b"bbbbbbbbbbbbbbbb", 4096, 2, 1, 32).unwrap();
+        assert_ne!(a, b);
+    }
+
+    #[test]
+    fn verify_rejects_garbage() {
+        assert!(!verify_password(PASSWORD, b"not-a-phc-string"));
+        assert!(!verify_password(PASSWORD, b""));
+    }
+
+    #[test]
+    fn params_validation() {
+        assert!(hash_password(PASSWORD, SALT, 0, 2, 1, 32).is_err());
+        // Salt too short (argon2 requires >= 8 bytes).
+        assert!(hash_password(PASSWORD, b"123", 4096, 2, 1, 32).is_err());
+    }
+}