fix: incorrect (package) javadoc for chacha and cmce

Signed-off-by: Leo Galambos <lg@hq.egothor.org>

lib/src/main/java/zeroecho/core/alg/chacha/package-info.java

@@ -33,56 +33,83 @@
  * POSSIBILITY OF SUCH DAMAGE.
  ******************************************************************************/
 /**
- * Classic McEliece (CMCE) KEM integration and utilities.
+ * ChaCha algorithm implementation and runtime wiring.
  *
  * <p>
- * This package adapts the Bouncy Castle PQC CMCE primitives to the core SPI. It
- * provides the algorithm descriptor, a runtime KEM context, and key
- * specifications for generation and import. The design keeps provider-specific
- * details encapsulated behind factories while exposing clear roles and metadata
- * to the higher layers.
+ * This package provides the ChaCha capability set for the core layer, including
+ * the stream cipher ChaCha20 and the AEAD construction ChaCha20-Poly1305. The
+ * module contains algorithm descriptors, streaming cipher contexts, immutable
+ * specifications, optional header codecs for runtime parameters, and symmetric
+ * key import/generation specifications. The design favors safe defaults
+ * (12-byte nonces, 128-bit AEAD tag), explicit role-to-context binding, and a
+ * clear separation between static configuration and per-operation parameters.
  * </p>
  *
- * <h2>Scope and responsibilities</h2>
- * <ul>
- * <li>Expose a concrete algorithm descriptor that registers CMCE KEM roles and
- * a KEM-backed message-agreement adapter.</li>
- * <li>Provide a runtime context that performs encapsulation and
- * decapsulation.</li>
- * <li>Define key specifications for key-pair generation and for importing X.509
- * and PKCS#8 encodings.</li>
- * </ul>
- *
  * <h2>Components</h2>
  * <ul>
- * <li><b>Algorithm descriptor:</b> {@link zeroecho.core.alg.cmce.CmceAlgorithm}
- * declares {@code ENCAPSULATE}/{@code DECAPSULATE} KEM roles and wires an
- * {@code AGREEMENT} role through a KEM-based adapter. It also registers
- * asymmetric key builders for generation and import. The provider requirement
- * is the Bouncy Castle PQC provider under the standard name
- * {@code "BCPQC"}.</li>
- * <li><b>Runtime context:</b> {@link zeroecho.core.alg.cmce.CmceKemContext}
- * holds state for encapsulation or decapsulation depending on which constructor
- * is used.</li>
- * <li><b>Key generation spec:</b> {@link zeroecho.core.alg.cmce.CmceKeyGenSpec}
- * selects a CMCE parameter set (variant) used by the key-pair builder.</li>
- * <li><b>Key import specs:</b> {@link zeroecho.core.alg.cmce.CmcePublicKeySpec}
- * wraps X.509 public keys and {@link zeroecho.core.alg.cmce.CmcePrivateKeySpec}
- * wraps PKCS#8 private keys; both are immutable and defensively copy their byte
- * arrays.</li>
+ * <li><b>Algorithm descriptors:</b> {@link ChaChaAlgorithm} registers ENCRYPT
+ * and DECRYPT roles for the ChaCha20 stream cipher;
+ * {@link ChaCha20Poly1305Algorithm} registers the AEAD counterpart. Both share
+ * a common base that wires symmetric key builders for generation and import.
+ * </li>
+ *
+ * <li><b>Streaming contexts:</b> {@link ChaChaCipherContext} and
+ * {@link ChaCha20Poly1305CipherContext} implement {@code InputStream}-to-
+ * {@code InputStream} transforms. The abstract parent
+ * {@link AbstractChaChaCipherContext} handles nonce lifecycle, optional header
+ * injection/parsing, and construction of a pull-based cipher stream.</li>
+ *
+ * <li><b>Static configuration (specs):</b> {@link ChaChaSpec} captures the
+ * initial counter and optional header codec for ChaCha20;
+ * {@link ChaCha20Poly1305Spec} binds the optional header codec for AEAD. The
+ * sealed marker {@link ChaChaBaseSpec} unifies both.</li>
+ *
+ * <li><b>Header codecs (optional):</b> {@link ChaChaHeaderCodec} writes/reads a
+ * compact header carrying the 12-byte nonce and a packed stream counter;
+ * {@link ChaCha20Poly1305HeaderCodec} writes/reads the 12-byte nonce and an
+ * optional SHA-256 of AAD to assert out-of-band AAD integrity.</li>
+ *
+ * <li><b>Key specifications:</b> {@link ChaChaKeyGenSpec} defines parameters
+ * for generating 256-bit ChaCha keys; {@link ChaChaKeyImportSpec} wraps
+ * externally supplied raw keys. Generation and import are registered by the
+ * algorithm base.</li>
  * </ul>
  *
- * <h2>Provider requirements</h2>
+ * <h2>Runtime parameters and context exchange</h2>
  * <p>
- * The algorithm expects the Bouncy Castle PQC provider to be installed before
- * use; the descriptor verifies this when generating or importing keys.
+ * Streaming contexts exchange ephemeral parameters through a Conflux session
+ * context using namespaced keys. For ChaCha20 and ChaCha20-Poly1305, a 12-byte
+ * nonce is required for each operation. On encryption, if the session context
+ * does not provide a nonce, the context generates a fresh value and stores it
+ * back into the session; on decryption the nonce must already be present and
+ * have the correct length. ChaCha20 also uses an initial counter sourced from
+ * {@link ChaChaSpec} and optionally overridden by the session context. When a
+ * header codec is configured and a session context is set, encryption prepends
+ * a minimal header and decryption reads it first to hydrate the session before
+ * initializing the cipher.
  * </p>
  *
+ * <h2>Safety and validation</h2>
+ * <ul>
+ * <li><b>Nonce uniqueness:</b> Applications must ensure nonces are unique per
+ * key. The contexts will generate nonces for encryption, but cross-process
+ * uniqueness is the caller's responsibility. Decryption fails if a nonce is
+ * missing or has an unexpected size.</li>
+ *
+ * <li><b>Counter policy (ChaCha20):</b> The default initial counter is 1. A
+ * context may override the spec value through the session key dedicated to
+ * counter exchange; consistency is enforced at attach time.</li>
+ *
+ * <li><b>AEAD tag and AAD (ChaCha20-Poly1305):</b> The effective tag length is
+ * 128 bits. If AAD is supplied, it is included in authentication; when enabled,
+ * the header codec can store SHA-256(AAD) to verify that decrypt-time AAD
+ * matches encrypt-time AAD.</li>
+ * </ul>
+ *
  * <h2>Thread-safety</h2>
  * <ul>
- * <li>Algorithm descriptors are immutable and safe to share across
- * threads.</li>
- * <li>Runtime contexts are stateful and not thread-safe.</li>
+ * <li>Algorithm descriptors are immutable and safe to share.</li>
+ * <li>Streaming contexts are stateful and not thread-safe.</li>
  * </ul>
  *
  * @since 1.0

lib/src/main/java/zeroecho/core/alg/cmce/package-info.java

@@ -33,70 +33,58 @@
  * POSSIBILITY OF SUCH DAMAGE.
  ******************************************************************************/
 /**
- * <h2>Classic McEliece (CMCE)</h2>
+ * Classic McEliece (CMCE) KEM integration and utilities.
  *
  * <p>
- * This package integrates the Classic McEliece cryptosystem, one of the oldest
- * and most studied code-based public-key cryptosystems. Originally proposed by
- * Robert McEliece in 1978, it is based on the hardness of decoding random
- * binary Goppa codes. Despite large public key sizes, the scheme has withstood
- * decades of cryptanalysis and remains unbroken by both classical and quantum
- * computers.
+ * This package adapts the Bouncy Castle PQC CMCE primitives to the core SPI. It
+ * provides the algorithm descriptor, a runtime KEM context, and key
+ * specifications for generation and import. The design keeps provider-specific
+ * details encapsulated behind factories while exposing clear roles and metadata
+ * to the higher layers.
  * </p>
  *
- * <h2>Post-quantum KEM</h2>
+ * <h2>Scope and responsibilities</h2>
+ * <ul>
+ * <li>Expose a concrete algorithm descriptor that registers CMCE KEM roles and
+ * a KEM-backed message-agreement adapter.</li>
+ * <li>Provide a runtime context that performs encapsulation and
+ * decapsulation.</li>
+ * <li>Define key specifications for key-pair generation and for importing X.509
+ * and PKCS#8 encodings.</li>
+ * </ul>
  *
+ * <h2>Components</h2>
+ * <ul>
+ * <li><b>Algorithm descriptor:</b> {@link zeroecho.core.alg.cmce.CmceAlgorithm}
+ * declares {@code ENCAPSULATE}/{@code DECAPSULATE} KEM roles and wires an
+ * {@code AGREEMENT} role through a KEM-based adapter. It also registers
+ * asymmetric key builders for generation and import. The provider requirement
+ * is the Bouncy Castle PQC provider under the standard name
+ * {@code "BCPQC"}.</li>
+ * <li><b>Runtime context:</b> {@link zeroecho.core.alg.cmce.CmceKemContext}
+ * holds state for encapsulation or decapsulation depending on which constructor
+ * is used.</li>
+ * <li><b>Key generation spec:</b> {@link zeroecho.core.alg.cmce.CmceKeyGenSpec}
+ * selects a CMCE parameter set (variant) used by the key-pair builder.</li>
+ * <li><b>Key import specs:</b> {@link zeroecho.core.alg.cmce.CmcePublicKeySpec}
+ * wraps X.509 public keys and {@link zeroecho.core.alg.cmce.CmcePrivateKeySpec}
+ * wraps PKCS#8 private keys; both are immutable and defensively copy their byte
+ * arrays.</li>
+ * </ul>
+ *
+ * <h2>Provider requirements</h2>
  * <p>
- * Classic McEliece has been selected by NIST in the post-quantum cryptography
- * standardization process for key encapsulation. Its primary appeal is
- * long-term confidence: no efficient attacks are known even in the quantum
- * setting. It provides IND-CCA2 security through a well-studied transform and
- * is especially suited for use cases where large public keys are acceptable but
- * extremely strong security margins are desired.
+ * The algorithm expects the Bouncy Castle PQC provider to be installed before
+ * use; the descriptor verifies this when generating or importing keys.
  * </p>
  *
- * <h2>Contents</h2>
+ * <h2>Thread-safety</h2>
  * <ul>
- * <li>{@link zeroecho.core.alg.cmce.CmceAlgorithm} – algorithm adapter exposing
- * CMCE as a KEM and agreement primitive.</li>
- * <li>{@link zeroecho.core.alg.cmce.CmceKemContext} – runtime context for
- * encapsulation and decapsulation.</li>
- * <li>{@link zeroecho.core.alg.cmce.CmceKeyGenSpec} – enumeration of
- * standardized CMCE parameter sets (variants).</li>
- * <li>{@link zeroecho.core.alg.cmce.CmcePublicKeySpec} – wrapper for
- * X.509-encoded public keys.</li>
- * <li>{@link zeroecho.core.alg.cmce.CmcePrivateKeySpec} – wrapper for
- * PKCS#8-encoded private keys.</li>
+ * <li>Algorithm descriptors are immutable and safe to share across
+ * threads.</li>
+ * <li>Runtime contexts are stateful and not thread-safe.</li>
  * </ul>
  *
- * <h2>Security properties</h2>
- * <ul>
- * <li>Underlying assumption: hardness of decoding binary Goppa codes.</li>
- * <li>Selected as a NIST post-quantum KEM standard (2022).</li>
- * <li>Public keys are large (hundreds of kilobytes), but ciphertexts and
- * secrets are compact.</li>
- * <li>Considered quantum-resistant and secure against known attacks.</li>
- * </ul>
- *
- * <h2>Usage</h2> <pre>{@code
- * // Select a variant (e.g., 8192128F for 256-bit security)
- * CmceKeyGenSpec spec = CmceKeyGenSpec.mceliece8192128f();
- * CmceAlgorithm alg = new CmceAlgorithm();
- * KeyPair kp = alg.asymmetricKeyBuilder(CmceKeyGenSpec.class).generateKeyPair(spec);
- *
- * // Encapsulation (sender)
- * try (CmceKemContext ctx = new CmceKemContext(alg, kp.getPublic())) {
- *   KemResult kem = ctx.encapsulate();
- *   byte[] ct = kem.ciphertext();
- *   byte[] secret = kem.secret();
- * }
- *
- * // Decapsulation (recipient)
- * try (CmceKemContext ctx = new CmceKemContext(alg, kp.getPrivate())) {
- *   byte[] secret = ctx.decapsulate(ct);
- * }
- * }</pre>
- *
  * @since 1.0
  */
 package zeroecho.core.alg.cmce;