Post-quantum cryptographic security engine for protecting data, keys, and identities.
A plain-language tour of the project lives on the website: nexus-q.link.

Current project status (2026-10-19): the workspace is versioned 4.1.0 — the stable line release of the V4 work, ready for the final independent audit. V1 (v1.0.0), V2 (v2.0.0) and V3 (v3-engineering-2026-10-09) are retained engineering baselines; V4 native-backend work is integrated into main by PR #54 at commit 1c03968 and was tagged v4-engineering-2026-10-16 as an engineering snapshot before this release line. The official 1.5× median-and-p95 performance gate passed in the reviewed native-backend CI, and PR #55 wires the backend into nexusq-core behind an explicitly opt-in native-backend feature. The native backend remains experimental: the default nexusq-core build, the CLI and the SDKs still use RustCrypto for production call paths; the native path is opt-in only and is not enabled by default anywhere. The production-path benchmark (native vs RustCrypto vs AWS-LC) passed the unchanged 1.5× median-and-p95 gate. Do not infer an independent audit, FIPS 140-3 validation, production readiness, or v1.0 release readiness. Evaluation commands and feature scope are documented in docs/performance/NATIVE_BACKEND_FEATURE.md. See docs/performance/NATIVE_BACKEND.md and docs/V3_V4_ROADMAP.md. Published package channels verified on 2026-10-19: crates.io (Rust library, core, CLI, server, C SDK and PQC crates), PyPI, npm, RubyGems, Maven Central (Java and Kotlin), Packagist, Go via pkg.go.dev, and Swift Package Manager (Git tag 4.1.0). NuGet and pub.dev did not resolve public packages at verification time and are not described as published; see the Installation section.

NEXUS-Q is a post-quantum cryptographic security engine designed to protect:

It is intended as a cryptographic/security engine for applications and servers. The repository also defines hardware-provider abstraction points for future TPM, HSM, Secure Element, enclave and RISC-V integrations; the default software backend does not itself provide hardware isolation.

Every operation goes through the same building blocks: a password unlocks an encrypted vault (format F-01, atomic writes), keys are managed through their full lifecycle, data is protected with envelope encryption (format F-02), a deny-by-default policy engine gates actions, and security-relevant events go to an HMAC-authenticated audit log with rollback anchoring.

1. We do not invent cryptography. Only standardized algorithms and maintained cryptographic libraries; dependency audit status is documented explicitly.
2. Library-first. The core is a Rust library; the CLI, SDKs and server are layers on top.
3. Hardware-agnostic boundary. Hardware-provider interfaces are separated from the software backend; concrete hardware isolation is only claimed when a provider is implemented and tested.
4. Zeroization. Secrets are wiped from memory when no longer needed.
5. Auditability. Auditable security state changes and cryptographic actions are recorded in a tamper-evident, HMAC-authenticated log.
6. Security from the ground up. Threat model and cryptographic rules before code.

Requirements: Rust 1.85 or newer (edition 2024) and Git. Additional SDK toolchains are only required when building a specific binding (C/C++, Python, Go, Ruby).

Target platforms: Linux (x86_64, aarch64); Android / Termux (aarch64); RISC-V (riscv64gc-unknown-linux-gnu), build verified; macOS and Windows release builds are validated by the V2 CI/release gate.

The reference document is docs/CRYPTOGRAPHY.md. Planned algorithms must not be described as available until they are implemented and tested.

Completed:

• Foundation documents, threat model, cryptographic rules.
• Crypto core: ML-KEM-768 hybrid with X25519, AES-256-GCM, ChaCha20-Poly1305, Ed25519, SHA-2, SHA-3, Argon2id, HKDF.
• Key management with full lifecycle.
• Encrypted vault (format F-01) with atomic writes.
• Envelope encryption (format F-02).
• Identities with signing, verification, rotation, revocation and signed credentials.
• Hardware abstraction traits for software, TPM, HSM, Secure Element and RISC-V.
• TRNG support with health checks and mixing.
• Cross-compilation to RISC-V verified.
• Storage: HMAC-authenticated audit log with rollback anchoring, backup bundle, storage DB.
• Policy engine with deny-by-default.
• CLI covering vault, key, data, sign, identity, credential and audit commands.

NEXUS-Q is not presented as a universal performance leader. On the v4.1.0 stable line, the opt-in native backend measures 0.86×–1.05× of AWS-LC median latency across the nine ML-KEM and ML-DSA operations on the same CI runner, passing the official 1.5× median-and-p95 gate on every operation. The default nexusq-core build, the CLI and the SDKs still use RustCrypto for production call paths; the native path is opt-in and experimental. Lower latency is better.

_{v4.1.0 stable line, 2026-10-19: official 1.5× median-and-p95 production-path gate (opt-in native backend vs AWS-LC) from the green release CI on the merged v4.1.0 code — three alternating rounds per implementation, pooled medians and nearest-rank p95, 3,000 samples per operation per implementation on an AMD EPYC 7763 CI runner. The full PQC Benchmark Arena run of the same release (241 normalized measurements, eight comparators plus the V1/V1+zeroize/V3 controls) is retained as CI artifacts. Reported without a composite score.}

The v1 baseline was slower than the fastest mature implementations on the measured ML-KEM and ML-DSA operations; closing that gap was the primary engineering target of the V4 line.

_{Final v1.0 Arena run, 2026-10-05: 57 normalized measurements from eight implementations on the same x86_64 Linux CI environment, 20 iterations and 3 warmups. Reported without a composite score. Comparators: AWS-LC, Botan, CIRCL, liboqs, OpenSSL, PQ Code Package and RustCrypto KEMs. Raw measurements are retained as CI artifacts.}

The final benchmark record does not claim a performance improvement over V1. Corrected Arena runs produced geometric means of 0.885 and 1.0647513576 V2/V1, so performance remains an unresolved investigation item rather than a validated regression or improvement. The latest same-runner comparison measured V2 at +0.22% to +52.37% latency versus V1 across the nine NEXUS-Q operations; ML-DSA-65 signing is the dominant outlier at +52.37%.

These are same-runner reference measurements from the retained Arena JSONL artifacts. The previous corrected run measured 0.885 V2/V1, demonstrating substantial run-to-run variance; V3 therefore begins with profiling and benchmark-variance investigation rather than assuming a single-run regression. See docs/V2_PERFORMANCE_RESULTS.md. Performance investigation is intentionally deferred to V3; V2 is not being modified to manufacture a benchmark result.

The paired V1/V3 investigation found median increases of +2.70% to +6.33% across the six measured ML-KEM operations in the recorded hosted-runner experiment; conventional ML-DSA verification was +6.40%, key generation +6.82%, and signing median -0.76%. These are observations from one CI runner and ten paired rounds, not universal performance claims. See BENCHMARKS.md and the forensic report.

The ML-DSA-only zeroize control does not prove SHA3/SHAKE zeroization is the cause of the ML-KEM latency delta. Issue #41 was closed by explicit project decision: V1 prioritizes speed, while V3 retains security hardening and accepts the observed performance cost.

The v4.1.0 stable line release was validated on main with the full PQC Benchmark Arena and the official 1.5× median-and-p95 production-path gate; both are green on the release code (a post-merge compile fix for the pinned Rust 1.85.1 release toolchain landed as PR #57).

Arena run (2026-10-19, commit 70152eb): 241 normalized measurements on the same ubuntu-24.04 x86_64 CI environment, 20 iterations and 3 warmups per operation. Comparators: AWS-LC (ec05f25), Botan 3.13.0, OpenSSL 3.5.9, CIRCL 1.6.4, RustCrypto KEMs, liboqs 0.16.0 and PQ Code Package, plus the retained V1 / V1+zeroize / V3 controls. Raw JSONL measurements are retained as CI artifacts of the Arena run; reported without a composite score.

Production-path gate (native backend vs AWS-LC, three alternating rounds per implementation, pooled medians and nearest-rank p95, 3,000 samples per operation per implementation): all nine operations passed the unchanged 1.5× median-and-p95 gate on the merged release code (gate run).

These are single-runner CI measurements on an AMD EPYC 7763 hosted runner, not universal performance claims. The native backend remains experimental and opt-in; the default nexusq-core build, the CLI and the SDKs still use RustCrypto for production call paths. See docs/performance/NATIVE_BACKEND_FEATURE.md and docs/V4_RELEASE.md.

V3 consolidates the hardened implementation, reproducible PQC Benchmark Arena, dependency/profile diagnostics, corrected benchmark sampling and archived evidence. Its GitHub release is an engineering release, not a claim of independent audit, certification, or registry publication. V1/V2/V3 artifacts and checksums are indexed in artifact-archive/README.md.

V4 is now represented by the v4-engineering-2026-10-16 engineering tag and is integrated into main. The native backend and its benchmark harness are present, and the official 1.5× median-and-p95 gate passed in the reviewed CI evidence. PR #55 wires the backend into nexusq-core behind an explicitly opt-in native-backend feature; the default build and all SDKs still use RustCrypto, the feature is not enabled by default anywhere, and the production-path benchmark passed the unchanged 1.5× median-and-p95 gate. It remains experimental and is not independently audited; the Phase 21 external audit is still open. The former Issue #48 tracking item is closed; its checklist is retained as historical engineering evidence under docs/performance/.

The v2 engineering line is frozen on nexusqv2 at version 2.0.0. V2 preserves the v1 security model while adding the completed performance, correctness/interoperability, security/fuzzing, backend-strategy and release gates. The GitHub V2.0.0 engineering release is historical; crates.io, PyPI and other SDK registries remain separate publication operations. See docs/V2_ROADMAP.md, docs/V2_RELEASE.md and docs/V2_BENCHMARK_BASELINE.md.

The v1.0 engineering baseline is complete and intentionally frozen. The final CI/Arena evidence established a reproducible reference point for correctness, security gates, deployment, documentation and PQC performance. The v1 baseline is not presented as a performance leader, and no unsupported production-certification or independent-audit claim is made. External registry/package publication is intentionally deferred. See BENCHMARKS.md and docs/ROADMAP.md.

# build the workspace
cargo build --workspace --release

# create and inspect a vault
./target/release/nexusq vault create ./example.nqv
./target/release/nexusq vault status ./example.nqv
./target/release/nexusq health

# generate a signing key (prefer --password-file over typing a password)
./target/release/nexusq key generate ./example.nqv --algorithm ed25519 --purpose sign --password-file ./password.txt

# encrypt and decrypt data
./target/release/nexusq data encrypt ./example.nqv --key-id <key-id> ./secret.txt
./target/release/nexusq data decrypt ./example.nqv ./secret.txt.nqx ./secret.out

Treat password.txt as a secret: restrict its permissions and never commit it. For development, cargo build and cargo test work as usual, and the CLI binary is at target/debug/nexusq. To build for RISC-V see docs/CROSS_COMPILE.md.

Release deployment:

cargo build --workspace --release
./deploy/package-release.sh

The generated archive contains the CLI, server, non-secret configuration example, deployment documentation, and SHA-256 manifests. It does not contain production tokens, vaults, private keys, or logs. For server installation and operations see docs/DEPLOYMENT.md and docs/SERVER.md.

The 4.1.0 stable line has published packages across several language registries; availability varies by SDK, and NuGet/pub.dev were not visible at verification time. The installation channel for each SDK:

Notes:

• The Go, PHP, Ruby, TypeScript, Java (JNA), Kotlin (JNA) and Dart bindings are thin FFI wrappers over the C SDK (libnexusq); build and install the C library first. The C#/.NET binding uses P/Invoke and the Swift binding links the C SDK through a Swift Package Manager system-library target, so both need the C library built and on the loader path as well.

• The Python package is a native extension module built from crates/nexusq-py (PyO3).

• Java and Kotlin are published on Maven Central:

  <!-- Maven -->
  <dependency>
    <groupId>io.github.lecodev-26</groupId>
    <artifactId>nexusq</artifactId>
    <version>4.1.0</version>
  </dependency>
  <!-- Kotlin: artifactId nexusq-kotlin, same group and version -->

  // Gradle (Kotlin DSL)
  implementation("io.github.lecodev-26:nexusq:4.1.0")
  implementation("io.github.lecodev-26:nexusq-kotlin:4.1.0")

• The C SDK is consumable directly from C and C++.

• The GitHub release archive ships the CLI and server binaries, not the C SDK; build the C library from source or install it via cargo.

• Registry availability is a distribution channel, not a validation claim; see the security and assurance section below.

User-facing documentation starts at docs/user/README.md. Technical and reference documentation lives in docs/:

V1–V4 are engineering version lines/snapshots, not proof of production readiness. A GitHub release does not imply an independent security audit, certification, FIPS validation, or production readiness; the same applies to registry publication, which is a distribution channel and not a validation claim. The V4 native backend remains experimental and opt-in; it is wired into nexusq-core behind the native-backend feature but is not enabled by default in the core, CLI, server, or SDKs. The performance gate result applies to the benchmarked backend and must not be read as an end-to-end application performance claim. Check current main CI before relying on any validation statement.

Report suspected vulnerabilities privately through GitHub Security Advisories. See SECURITY.md.

Dual-licensed under your choice of the MIT License or the Apache License 2.0. This follows the Rust ecosystem convention (the same choice as Rust, Tokio and Serde).