WASM builds temporarily unsupported in v0.3.3 due to getrandom 0.3.x upgrade

[AriajSarkar]

Summary

Building CrabGraph for the wasm32-unknown-unknown target is currently not supported in v0.3.3 due to a dependency version conflict introduced by the getrandom 0.2.x → 0.3.4 upgrade.

Root Cause

Cargo's unified feature resolution cannot enable different features for different versions of the same crate. When building for WASM:

Two versions of getrandom are required simultaneously:

1. getrandom 0.2.x (transitive dependency)

   • Via: ed25519-dalek 2.2.0 → rand_core 0.6.4 → getrandom 0.2.x
   • Requires: js feature flag for WASM support

2. getrandom 0.3.4 (direct dependency)

   • Our explicit dependency for random number generation
   • Requires: wasm_js feature flag for WASM support

The Conflict:

• getrandom 0.2.x has js feature (removed in 0.3.x)
• getrandom 0.3.x has wasm_js feature (didn't exist in 0.2.x)
• Cargo cannot enable both js and wasm_js for different versions

Impact

• ❌ Affected: wasm32-unknown-unknown target builds
• ✅ Unaffected: All other platforms (Windows, Linux, macOS, iOS, Android, other wasm targets)
• ✅ Workaround: Use CrabGraph v0.3.2 for WASM projects

Timeline for Resolution

This issue will be automatically resolved when upgrading to the next generation of Dalek cryptography crates:

Required Upgrades

ed25519-dalek = "3.0.0"      # Currently: 2.2.0 (stable)
x25519-dalek = "3.0.0"       # Currently: 2.0.1 (stable)

Current Status (as of November 2025):

• ed25519-dalek 3.0.0-pre.1 available (pre-release)
• x25519-dalek 3.0.0-pre.1 available (pre-release)
• Both use curve25519-dalek 4.x which depends on rand_core 0.9.x
• rand_core 0.9.x uses getrandom 0.3.x (compatible with our upgrade!)

Expected Stable Release: Q1 2026

MSRV Impact

Upgrading to Dalek 3.0 will require:

• Current MSRV: Rust 1.70
• New MSRV: Rust 1.81+ (required by ed25519-dalek 3.0)

Technical Details

Dependency Chain (Current - v0.3.3)

crabgraph 0.3.3
├── getrandom 0.3.4 (direct) ← needs wasm_js feature
├── ed25519-dalek 2.2.0
│   └── rand_core 0.6.4
│       └── getrandom 0.2.x ← needs js feature
└── x25519-dalek 2.0.1
    └── rand_core 0.6.4
        └── getrandom 0.2.x ← needs js feature

After Dalek 3.0 Upgrade (Future)

crabgraph 0.4.0
├── getrandom 0.3.4 (direct) ← wasm_js feature
├── ed25519-dalek 3.0.0
│   └── rand_core 0.9.x
│       └── getrandom 0.3.x ← wasm_js feature ✅
└── x25519-dalek 3.0.0
    └── rand_core 0.9.x
        └── getrandom 0.3.x ← wasm_js feature ✅

Action Items

For Users

• Need WASM support now? → Use CrabGraph v0.3.2
• Don't need WASM? → Use v0.3.3 (recommended - latest features)

For Maintainers

• Document limitation in CHANGELOG.md (v0.3.3)
• Add warning to README.md WASM feature description
• Add comments in Cargo.toml explaining the issue
• Monitor ed25519-dalek 3.0 stable release
• Monitor x25519-dalek 3.0 stable release
• Create upgrade PR when stable versions available
• Bump MSRV to 1.81 in upgrade PR
• Test WASM build after upgrade
• Update CHANGELOG.md noting WASM support restored

Alternative Solutions Considered

❌ Downgrade getrandom back to 0.2.x

• Pro: Immediate WASM fix
• Con: Miss security improvements and new features in 0.3.x
• Con: getrandom 0.2.x is older, will eventually be deprecated
• Decision: Not chosen - forward compatibility preferred

❌ Upgrade to Dalek 3.0-pre now

• Pro: Immediate WASM fix
• Con: Pre-release versions (not production-ready)
• Con: Requires MSRV bump to 1.81 (breaking for users on older Rust)
• Decision: Not chosen - wait for stable releases

✅ Document limitation and wait for stable Dalek 3.0

• Pro: Gets getrandom 0.3.4 improvements immediately
• Pro: Users on older Rust versions unaffected
• Pro: Clear upgrade path when ecosystem ready
• Con: Temporary WASM limitation
• Decision: Chosen - best balance of stability and progress

Related Dependencies Waiting for Stable Releases

When Dalek 3.0 is stable, we can also consider upgrading the broader RustCrypto ecosystem (all currently RC):

# AEAD
aes-gcm = "0.11.0"              # Currently: 0.10.3
chacha20poly1305 = "0.11.0"     # Currently: 0.10.1

# KDF
pbkdf2 = "0.13.0"               # Currently: 0.12.2
argon2 = "0.6.0"                # Currently: 0.5.3
hkdf = "0.13.0"                 # Currently: 0.12.4

# Hash
sha2 = "0.11.0"                 # Currently: 0.10.9
sha3 = "0.11.0"                 # Currently: 0.10.8
blake2 = "0.11.0"               # Currently: 0.10.6
hmac = "0.13.0"                 # Currently: 0.12.1

# Key Wrap
aes-kw = "0.3.0"                # Currently: 0.2.1

# Other
pkcs8 = "0.11.0"                # Currently: 0.10.2
rsa = "0.10.0"                  # Currently: 0.9.8 (fixes num-bigint-dig deprecation)

Note: All these are coordinated releases - likely to go stable together in Q1 2026.

Testing Checklist (For Future Fix PR)

When creating the fix PR after Dalek 3.0 stable release:

• Update ed25519-dalek to 3.0.0 in Cargo.toml
• Update x25519-dalek to 3.0.0 in Cargo.toml
• Update rust-version to 1.81 in Cargo.toml
• Remove target-specific getrandom dependency (no longer needed)
• Restore wasm feature flag to wasm = ["getrandom/wasm_js"]
• Remove WASM limitation comments from Cargo.toml
• Test: cargo build --target wasm32-unknown-unknown --features wasm
• Test: All 313 tests still pass
• Test: Clippy passes with zero warnings
• Test: Ed25519/X25519 examples still work
• Update CHANGELOG.md noting WASM support restored
• Update README.md removing WASM limitation warning
• Bump version to 0.4.0 (MSRV bump = minor version bump)

References

• getrandom 0.3.x migration guide: https://docs.rs/getrandom/0.3.4/getrandom/
• ed25519-dalek 3.0 tracking: https://github.com/dalek-cryptography/curve25519-dalek/discussions
• RustCrypto 0.11 tracking: https://github.com/RustCrypto/traits/issues
• Cargo feature resolution: https://doc.rust-lang.org/cargo/reference/features.html#feature-unification

[AriajSarkar]

📋 Current Status (v0.3.3)

WASM Support: ❌ Not Available

Why: Dependency version conflict

• Our code: getrandom 0.3.4 (needs wasm_js feature)
• ed25519-dalek/x25519-dalek: getrandom 0.2.x via rand_core 0.6 (needs js feature)
• Cargo can't enable different features for different versions

Workaround: Use CrabGraph v0.3.2 for WASM projects

---

🎯 Resolution Plan

When: After ed25519-dalek 3.0 and x25519-dalek 3.0 stable releases (expected Q1 2026)

What Will Change:

Version Updates

# CrabGraph
version = "0.4.0"  # MSRV bump = minor version
rust-version = "1.81"  # Up from 1.70

# Dependencies
ed25519-dalek = "3.0.0"    # Up from 2.2.0
x25519-dalek = "3.0.0"     # Up from 2.0.1

Why This Fixes WASM

Both Dalek 3.0 crates will use:

• curve25519-dalek 4.x → rand_core 0.9.x → getrandom 0.3.x ✅

This aligns with our direct getrandom 0.3.4 dependency, eliminating the version conflict!

Bonus: Full RustCrypto Update

When Dalek 3.0 is stable, RustCrypto's 0.11/0.13 releases will likely also be stable. We can upgrade:

AEAD: aes-gcm 0.11, chacha20poly1305 0.11
KDF: pbkdf2 0.13, argon2 0.6, hkdf 0.13
Hash: sha2 0.11, sha3 0.11, blake2 0.11, hmac 0.13
Other: pkcs8 0.11, rsa 0.10 (fixes num-bigint-dig deprecation)

---

🚀 What to Expect

Future PR (v0.4.0) will:

1. ✅ Restore full WASM support (wasm32-unknown-unknown builds)
2. ✅ Update to Dalek 3.0 (latest ed25519/x25519 implementations)
3. ✅ Update entire RustCrypto ecosystem to latest stable
4. ⚠️ Require Rust 1.81+ (MSRV bump)
5. ✅ Maintain 100% backward compatible API (no code changes needed)

No Breaking Changes to YOUR Code:

• All public APIs remain the same
• Only dependency versions and MSRV change
• Existing code will compile without modification (if on Rust 1.81+)

---

📊 Tracking Upstream Releases

Monitor these for stable releases:

Crate	Current (Stable)	Latest (RC/Pre)	Rust Version	Status
ed25519-dalek	2.2.0	3.0.0-pre.1	1.81+	🟡 Pre-release
x25519-dalek	2.0.1	3.0.0-pre.1	1.81+	🟡 Pre-release
aes-gcm	0.10.3	0.11.0-rc.2	1.65+	🟡 RC
chacha20poly1305	0.10.1	0.11.0-rc.2	1.65+	🟡 RC
sha2	0.10.9	0.11.0-rc.3	1.72+	🟡 RC
rsa	0.9.8	0.10.0-rc.10	1.73+	🟡 RC

Subscribe to:

• https://github.com/dalek-cryptography/curve25519-dalek (Dalek releases)
• https://github.com/RustCrypto/AEADs (AEAD releases)
• https://github.com/RustCrypto/hashes (Hash releases)

---

Note: This issue will remain open after the v0.3.3 release and will be closed only when v0.4.0 (with full WASM support) is released.

[AriajSarkar]

⚠️ Version Update Notice (February 2026)

The version references in this issue body are now outdated due to the TLS CryptoProvider implementation:

Original Version Timeline (Now Outdated)

• v0.3.3 → v0.4.0 upgrade path mentioned in "After Dalek 3.0 Upgrade" section
• Testing checklist references v0.4.0 for MSRV bump

Current Status

• v0.4.0-pre is now available with TLS CryptoProvider support (P-256, P-384, SHA-384)
• The TLS feature adds new dependencies that don't conflict with the WASM issue
• WASM limitation still exists and will be resolved when Dalek 3.0 goes stable

Updated Dependency Chain (v0.4.0-pre)

crabgraph 0.4.0-pre
├── getrandom 0.3.4 (direct) ← needs wasm_js feature
├── ed25519-dalek 2.2.0
│   └── rand_core 0.6.4
│       └── getrandom 0.2.x ← needs js feature (CONFLICT REMAINS)
├── x25519-dalek 2.0.1
│   └── rand_core 0.6.4
│       └── getrandom 0.2.x ← needs js feature (CONFLICT REMAINS)
├── p256 0.13 (NEW - TLS feature)
├── p384 0.13 (NEW - TLS feature)
└── rustls 0.23 (NEW - TLS feature)

The core WASM issue (getrandom 0.2.x vs 0.3.x conflict) remains unchanged. This will be fully resolved when upgrading to ed25519-dalek 3.0 / x25519-dalek 3.0 stable releases.