feat: crypto library, Nexus HTTP server, JWT CLI, Boko web framework

- lib/crypto/: 9-module crypto library (Hash, HMAC, Base64/URL, Random, AES, RSA, ECDSA, Ed25519, JWT) - rt/runtime.c: +346 lines OpenSSL crypto primitives (SHA-1/384/512, HMAC, Base64URL, AES-CBC/GCM, RSA, ECDSA, Ed25519) - apps/nexus/: multi-threaded HTTP/1.1 + HTTP/2 detect + WebSocket server - apps/jwt-pitbul/: JWT CLI tool (sign, verify, decode, keygen) - apps/boko-framework/: FastAPI-inspired async web framework - test_crypto/: crypto library test suite (23 tests)
2026-06-07 22:15:00 +03:00
parent a2617e9954
commit e7e900973f
47 changed files with 3983 additions and 6 deletions
@@ -0,0 +1,175 @@
+# jwt-pitbul
+
+**JWT CLI tool for the Bux ecosystem — sign, verify, decode, and key generation.**
+
+A standalone command-line utility for working with JSON Web Tokens (RFC 7519). Built on `Std::Crypto`, backed by OpenSSL.
+
+## Quick Start
+
+```bash
+cd apps/jwt-pitbul
+../../buxc build
+./jwt-pitbul
+```
+
+## Commands
+
+### `sign` — Create a JWT
+
+```
+jwt-pitbul sign <alg> <key> <claims_json>
+```
+
+| Argument | Description |
+|----------|-------------|
+| `<alg>` | Algorithm: `HS256`, `HS384`, `HS512`, `RS256`, `RS384`, `RS512`, `ES256`, `ES384`, `EdDSA` |
+| `<key>` | HMAC secret string, or path to PEM file (RSA/ECDSA), or base64 raw key (Ed25519) |
+| `<claims_json>` | JSON payload string (e.g. `{"sub":"123","exp":1735689600}`) |
+
+```bash
+# HMAC
+jwt-pitbul sign HS256 'my-secret-key' '{"sub":"123","role":"admin"}'
+
+# RSA (private key from file)
+jwt-pitbul sign RS256 private.pem '{"sub":"456"}'
+
+# ECDSA
+jwt-pitbul sign ES256 ec_private.pem '{"sub":"789"}'
+
+# Ed25519 (base64-encoded 32-byte private key)
+jwt-pitbul sign EdDSA 'MC4CAQAwBQYDK2VwBCIEIJ...' '{"sub":"000"}'
+```
+
+### `verify` — Verify and decode
+
+```
+jwt-pitbul verify <token> <alg> <key>
+```
+
+```bash
+jwt-pitbul verify eyJhbGciOiJ... HS256 'my-secret-key'
+# ✓ Signature valid
+#
+# Header:
+# {"alg":"HS256","typ":"JWT"}
+#
+# Payload:
+# {"sub":"123","role":"admin"}
+```
+
+### `decode` — Decode without verification
+
+```
+jwt-pitbul decode <token>
+```
+
+```bash
+jwt-pitbul decode eyJhbGciOiJ...
+# Decoded (no verification):
+#
+# Header:
+# {"alg":"HS256","typ":"JWT"}
+#
+# Payload:
+# {"sub":"123"}
+#
+# Signature (base64url): xxxxxxxxx...
+```
+
+### `keygen` — Generate keys
+
+```
+jwt-pitbul keygen <type>
+```
+
+| Type | Output |
+|------|--------|
+| `ed25519` | Generates an Ed25519 keypair (prints base64 public/private keys) |
+| `rsa` | Prints OpenSSL CLI commands to generate RSA 2048-bit keys |
+| `ecdsa` | Prints OpenSSL CLI commands to generate ECDSA P-256 keys |
+
+```bash
+jwt-pitbul keygen ed25519
+# Ed25519 keypair (base64):
+#   Public:  MCowBQYDK2VwAyEA...
+#   Private: MC4CAQAwBQYDK2VwBCIEIJ...
+
+jwt-pitbul keygen rsa
+# RSA key generation requires OpenSSL CLI:
+#   openssl genpkey -algorithm RSA -out private.pem -pkeyopt rsa_keygen_bits:2048
+#   openssl rsa -in private.pem -pubout -out public.pem
+```
+
+## Supported Algorithms
+
+| Algorithm | Type | Key Format |
+|-----------|------|------------|
+| HS256 | HMAC-SHA256 | Raw secret string |
+| HS384 | HMAC-SHA384 | Raw secret string |
+| HS512 | HMAC-SHA512 | Raw secret string |
+| RS256 | RSA PKCS#1 v1.5 SHA-256 | PEM file path |
+| RS384 | RSA PKCS#1 v1.5 SHA-384 | PEM file path |
+| RS512 | RSA PKCS#1 v1.5 SHA-512 | PEM file path |
+| ES256 | ECDSA P-256 | PEM file path |
+| ES384 | ECDSA P-384 | PEM file path |
+| EdDSA | Ed25519 | Base64 32-byte raw key |
+
+## Generating Keys with OpenSSL
+
+### RSA 2048-bit
+
+```bash
+openssl genpkey -algorithm RSA -out private.pem -pkeyopt rsa_keygen_bits:2048
+openssl rsa -in private.pem -pubout -out public.pem
+```
+
+### ECDSA P-256
+
+```bash
+openssl ecparam -genkey -name prime256v1 -noout -out ec_private.pem
+openssl ec -in ec_private.pem -pubout -out ec_public.pem
+```
+
+### ECDSA P-384
+
+```bash
+openssl ecparam -genkey -name secp384r1 -noout -out ec_private.pem
+openssl ec -in ec_private.pem -pubout -out ec_public.pem
+```
+
+### Ed25519
+
+```bash
+# In-app generation:
+jwt-pitbul keygen ed25519
+
+# Or via OpenSSL:
+openssl genpkey -algorithm Ed25519 -out ed25519_private.pem
+openssl pkey -in ed25519_private.pem -pubout -out ed25519_public.pem
+```
+
+## Error Codes
+
+| Exit | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | Error (invalid arguments, bad signature, missing file, etc.) |
+
+## Building
+
+```bash
+cd apps/jwt-pitbul
+../../buxc build      # Bootstrap compiler (Nim)
+# or
+../../buxc_lir build  # Self-hosted compiler
+```
+
+## Dependencies
+
+- Bux standard library (`Std::Crypto`, `Std::Io`, `Std::String`)
+- OpenSSL 1.1.1+ (linked via runtime)
+- Bux compiler (`buxc` or `buxc_lir`)
+
+## License
+
+Part of the Bux project. See root [LICENSE](../../LICENSE).