feat: start CryptX Java XS bridge

dev/design/cryptx-port.md

@@ -0,0 +1,47 @@
+# CryptX Java XS Port
+
+## Current state
+
+The first functional API slice is implemented on branch
+`feature/cryptx-java-bridge`, based on master commit `d76b95e4093b24d9af782a69b2619a52d0b5ae6c`.
+It retains a pure-Perl `CryptX.pm` bootstrap and implements selected XS entry
+points in `CryptX.java` using the project's existing JCA and Bouncy Castle
+dependencies. PR #1220 tracks the broader port.
+
+This slice covers `Crypt::Misc` binary/base64/base64url helpers, octet
+increment, radix conversion, and equality; `Crypt::Digest` functional calls;
+and `Crypt::Mac::HMAC` functional calls. Digest and HMAC algorithm support is
+limited to names with a matching JCA or Bouncy Castle provider. Unsupported
+names raise Perl runtime exceptions. Stateful digest/MAC objects, cipher and
+mode families, public-key APIs, AEAD APIs, and remaining CryptX entry points
+are follow-on work.
+
+## Decisions
+
+- Preserve the CPAN Perl wrappers and replace the XS boundary in Java; do not
+  duplicate the wrappers or translate LibTomCrypt's C implementation
+  mechanically.
+- Reuse JCA and the already bundled Bouncy Castle provider. Keep provider
+  failures explicit and retain Perl-compatible `undef` behavior for malformed
+  base64 input.
+- Add coverage first for functional APIs that directly support JWT-style
+  consumers. Validate focused tests against native CryptX before relying on
+  them under PerlOnJava.
+
+## Progress
+
+| Phase | Delivered scope | Evidence | Status |
+|---|---|---|---|
+| 1 | CryptX bootstrap; binary/base64url helpers; functional digests and HMAC | System Perl: 12/12 focused assertions. PerlOnJava: focused bundled-module test passed. `nice -n 19 make`: passed. | In review |
+
+## Next work
+
+Implement stateful digest and HMAC APIs, then add RSA signing/verification by
+reusing `Crypt::OpenSSL::RSA` key parsing and signing paths. Expand to ECC/ECDH
+and common AEAD APIs after the first downstream HS/RS JWT acceptance tests.
+
+## References
+
+- [CryptX port issue #1220](https://github.com/fglock/PerlOnJava/issues/1220)
+- [XS compatibility inventory](../../docs/reference/xs-compatibility.md)
+- [CPAN module porting guide](../../docs/guides/module-porting.md)

docs/about/changelog.md

@@ -6,6 +6,8 @@ priorities and future plans.
 
 ## Work in progress
 
+- Add an initial CryptX Java XS bridge for binary/base64url helpers, functional digests, and HMAC using the existing JCA and Bouncy Castle providers (#1220).
+
 - Preserve named typeglob stringification when copying package stash entries (#1927).
 
 - Reduce repeated eval STRING overhead with lazy state and caching for context-free integer-literal evals (#1911).

docs/reference/bundled-modules.md

@@ -11,6 +11,7 @@ Recent CPAN compatibility additions include:
 
 | Module | Implementation | Notes |
 |--------|----------------|-------|
+| `CryptX` | Perl bootstrap + Java XS bridge | Functional base64, digest, and HMAC entry points; broader CryptX APIs remain incomplete |
 | `Future::AsyncAwait` | Bundled pure Perl module plus PerlOnJava async runtime | Native `async`/`await` syntax and upstream-compatible Future integration |
 | `JSON::DWIW` | Pure Perl over bundled `JSON::PP` | Relaxed legacy JSON API, file conversion, booleans, and compatibility helpers |
 | `Taint::Runtime` | Perl + Java XS bridge | Runtime taint toggling and scalar taint inspection |
@@ -305,6 +306,7 @@ These are loaded automatically or via `use`:
 | `Digest::MD5` | Java | `java.security.MessageDigest` |
 | `Digest::SHA` | Java | `java.security.MessageDigest` |
 | `Digest` | Perl | |
+| `CryptX` | Perl + Java | Functional `Crypt::Misc` binary/base64url helpers, `Crypt::Digest` functional calls, and `Crypt::Mac::HMAC`; OO APIs and other crypto families are not yet covered |
 | `Crypt::Twofish2` | Java + Perl | Uses the bundled BouncyCastle provider; passes all 83 upstream vectors |
 | `Crypt::Rijndael` | Java + Perl | Uses the JCA AES provider; supports the upstream ECB, CBC, CFB128, OFB, and CTR API |
 | `MIME::Base64` | Java | |

docs/reference/feature-matrix.md

@@ -910,6 +910,9 @@ The `:encoding()` layer supports all encodings provided by Java's `Charset.forNa
   upstream-compatible ECB, CBC, and CFB1 modes.
 - ✅  **Crypt::Rijndael**: Java XS replacement backed by the JCA AES provider,
   with upstream-compatible ECB, CBC, CFB128, OFB, and CTR modes.
+- 🟡 **CryptX**: the upstream Perl bootstrap and a Java XS subset provide
+  base64 helpers, functional digests, and HMAC through JCA/Bouncy Castle;
+  stateful objects, ciphers, key APIs, and other XS families remain incomplete.
 - ✅  **Tie::Array::Packed**: Java XS replacement for packed tied-array
   storage, mutation, splicing, rotation, and binary search.
 - 🟡 **B::Flags**: portable OP/SV flag names over the bundled partial `B`

docs/reference/xs-compatibility.md

@@ -21,6 +21,7 @@ These modules have optimized Java implementations built into PerlOnJava:
 | DateTime | DateTime.java | 1.65 | Uses java.time APIs, JulianFields.RATA_DIE |
 | Digest::MD5 | DigestMD5.java | - | Uses Java MessageDigest |
 | Digest::SHA | DigestSHA.java | - | Uses Java MessageDigest |
+| CryptX | CryptX.java | 0.091 | Functional binary/base64url helpers, selected digests, and HMAC; OO and other XS APIs remain incomplete |
 | Time::HiRes | TimeHiRes.java | - | Uses System.nanoTime() |
 | DBI | Dbi.java | - | JDBC backend |
 | Exporter::Lexical | ExporterLexical.java | 0.02 | Installs lexical subs into the enclosing compile-time scope |