These values correspond to the documented constants in the Python - * reference. Protocol version and algorithm strings are immutable and - * must never be changed — they are used for downgrade detection.
+ * Protocol, crypto, and configuration constants. Immutable — used for downgrade detection. */ public final class Constants { // ── Protocol Constants ────────────────────────────────────────── /** - * Protocol version string. Never change — used for downgrade detection. + * Protocol version — never change (downgrade detection). */ public static final String PROTOCOL_VERSION = "1.0"; - /** - * Hybrid encryption algorithm identifier. Never change — used for downgrade detection. + * Hybrid encryption algorithm identifier — never change (downgrade detection). */ public static final String HYBRID_ALGORITHM = "hybrid-aes256-rsa4096"; - /** - * RSA-OAEP-SHA256 key wrapping algorithm identifier. + * RSA-OAEP-SHA256 key wrapping algorithm. */ public static final String KEY_WRAP_ALGORITHM = "RSA-OAEP-SHA256"; - /** - * AES-256-GCM payload encryption algorithm identifier. + * AES-256-GCM payload encryption algorithm. */ public static final String PAYLOAD_ALGORITHM = "AES-256-GCM"; // ── Cryptographic Constants ───────────────────────────────────── /** - * RSA key size in bits. Fixed at 4096. + * RSA key size in bits. */ public static final int RSA_KEY_SIZE = 4096; - /** - * RSA public exponent. Fixed at 65537. + * RSA public exponent. */ public static final int RSA_PUBLIC_EXPONENT = 65537; - /** - * AES key size in bytes (256-bit). Per-request ephemeral. + * AES key size in bytes (256-bit). */ public static final int AES_KEY_SIZE = 32; - /** - * GCM nonce size in bytes (96-bit). Per-request. + * GCM nonce size in bytes (96-bit). */ public static final int GCM_NONCE_SIZE = 12; - /** * GCM authentication tag size in bytes. */ public static final int GCM_TAG_SIZE = 16; - /** * Minimum RSA key size for validation (bits). */ @@ -69,7 +57,7 @@ public final class Constants { // ── Payload Limits ────────────────────────────────────────────── /** - * Maximum payload size in bytes (10 MB). Used for DoS protection. + * Maximum payload size in bytes (10 MB). */ public static final long MAX_PAYLOAD_SIZE = 10L * 1024 * 1024; @@ -79,61 +67,53 @@ public final class Constants { * Default HTTP request timeout in seconds. */ public static final int DEFAULT_TIMEOUT_SECONDS = 60; - /** - * Default number of retries on retryable errors. - * Exponential backoff: 1s, 2s, 4s… + * Default retries on retryable errors (exponential backoff: 1s, 2s, 4s…). */ public static final int DEFAULT_MAX_RETRIES = 2; - /** - * Set of HTTP status codes that are eligible for retry. + * Retryable HTTP status codes. */ public static final SetThis class provides a familiar API surface matching {@code openai.ChatCompletion.create()}. - * All requests are automatically encrypted using hybrid AES-256-GCM + RSA-4096 encryption - * before being sent to the NOMYO router.
- * - *{@code
- * SecureChatCompletion client = new SecureChatCompletion(
- * "https://api.nomyo.ai",
- * false,
- * "your-api-key",
- * true,
- * "/path/to/keys",
- * 2
- * );
- *
- * Map response = client.create(
- * "Qwen/Qwen3-0.6B",
- * List.of(Map.of("role", "user", "content", "Hello, world!"))
- * );
- * }
- *
- * Streaming is not supported. The server rejects streaming requests with HTTP 400. - * Always use {@code stream=false} (the default).
- * - *The {@code security_tier} parameter controls the hardware isolation level:
- *Set {@code keyDir} to a directory path to persist RSA keys to disk. - * Keys are generated on first use and reused across all calls. - * Set {@code keyDir} to {@code null} for ephemeral keys (in-memory only, lost on restart).
+ * High-level OpenAI-compatible entrypoint with automatic hybrid encryption (AES-256-GCM + RSA-4096). */ @Getter public class SecureChatCompletion { @@ -55,83 +17,45 @@ public class SecureChatCompletion { private final String keyDir; /** - * Constructs a {@code SecureChatCompletion} with default settings. - * - *Uses the default NOMYO router URL ({@code https://api.nomyo.ai}), - * HTTPS-only, secure memory enabled, ephemeral keys, and 2 retries.
+ * Default settings: {@code https://api.nomyo.ai}, HTTPS-only, secure memory, ephemeral keys, 2 retries. */ public SecureChatCompletion() { this(Constants.DEFAULT_BASE_URL, false, null, true, null, Constants.DEFAULT_MAX_RETRIES); } /** - * Constructs a {@code SecureChatCompletion} with the specified settings. - * - * @param baseUrl NOMYO Router base URL (HTTPS enforced unless {@code allowHttp} is {@code true}) - * @param allowHttp permit {@code http://} URLs (development only) - * @param apiKey Bearer token for authentication (can also be passed per-call via {@link #create}) - * @param secureMemory enable memory locking/zeroing (warns if unavailable) - * @param keyDir directory to persist RSA keys; {@code null} = ephemeral (in-memory only) - * @param maxRetries retries on 429/500/502/503/504 + network errors (exponential backoff: 1s, 2s, 4s…) + * @param baseUrl NOMYO Router base URL (HTTPS enforced unless {@code allowHttp}) + * @param allowHttp permit {@code http://} URLs (development only) + * @param apiKey Bearer token (can also be passed per-call via {@link #create}) + * @param secureMemory enable memory locking/zeroing + * @param keyDir RSA key directory; {@code null} = ephemeral + * @param maxRetries retries on 429/500/502/503/504 + network errors (exponential backoff) */ - public SecureChatCompletion( - String baseUrl, - boolean allowHttp, - String apiKey, - boolean secureMemory, - String keyDir, - int maxRetries - ) { + public SecureChatCompletion(String baseUrl, boolean allowHttp, String apiKey, boolean secureMemory, String keyDir, int maxRetries) { this.client = new SecureCompletionClient(baseUrl, allowHttp, secureMemory, maxRetries); this.apiKey = apiKey; this.keyDir = keyDir; } /** - * Creates a chat completion with the specified parameters. + * Main entrypoint — same signature as {@code openai.ChatCompletion.create()}. + * All kwargs are passed through to the OpenAI-compatible API. + *Streaming is not supported (server rejects with HTTP 400). + * Security tiers: "standard", "high", "maximum". * - *
This is the main entrypoint, with the same signature as - * {@code openai.ChatCompletion.create()}. Returns a map (not an object) - * containing the OpenAI-compatible response.
- * - *| Param | Type | Required | Description |
|---|---|---|---|
| {@code model} | {@code String} | yes | Model identifier, e.g. "Qwen/Qwen3-0.6B" |
| {@code messages} | {@code List | yes | OpenAI-format messages |
| {@code temperature} | {@code Double} | no | 0–2 |
| {@code maxTokens} | {@code Integer} | no | Maximum tokens in response |
| {@code topP} | {@code Double} | no | Top-p sampling parameter |
| {@code stop} | {@code String | List | no | Stop sequences |
| {@code presencePenalty} | {@code Double} | no | -2.0 to 2.0 |
| {@code frequencyPenalty} | {@code Double} | no | -2.0 to 2.0 |
| {@code n} | {@code Integer} | no | Number of completions |
| {@code bestOf} | {@code Integer} | no | |
| {@code seed} | {@code Integer} | no | Reproducibility seed |
| {@code logitBias} | {@code Map | no | Token bias map |
| {@code user} | {@code String} | no | End-user identifier |
| {@code tools} | {@code List | no | Tool definitions passed through to llama.cpp |
| {@code toolChoice} | {@code String} | no | "auto", "none", or specific tool name |
| {@code responseFormat} | {@code Map} | no | {"type": "json_object"} or {"type": "json_schema", ...} |
| {@code stream} | {@code Boolean} | no | NOT supported. Server rejects with HTTP 400. Always use {@code false}. |
| {@code baseUrl} | {@code String} | no | Per-call override (creates temp client internally) |
| {@code securityTier} | {@code String} | no | "standard", "high", or "maximum". Invalid values raise {@code ValueError}. |
| {@code apiKey} | {@code String} | no | Per-call override of instance {@code apiKey}. |
This class handles key management, hybrid encryption, HTTP communication - * with retry logic, and response decryption. It is the core of the NOMYO - * Java client and is used internally by {@link SecureChatCompletion}.
- * - *Encrypted payloads use hybrid encryption (AES-256-GCM + RSA-4096-OAEP-SHA256):
- *Client RSA keys are generated on first use (if not loaded from disk) and - * reused across all subsequent calls until the client is discarded. Keys can - * be persisted to disk via {@link #generateKeys(boolean, String, String)} or - * loaded from disk via {@link #loadKeys(String, String, String)}.
+ * Low-level client: key management, hybrid encryption, HTTP with retry, response decryption. Used by {@link SecureChatCompletion}. */ public class SecureCompletionClient { - // ── Instance Attributes ───────────────────────────────────────── - /** - * Base URL of the NOMYO router (trailing slash stripped). + * NOMYO router base URL (trailing slash stripped). */ @Getter private final String routerUrl; /** - * Whether HTTP (non-HTTPS) URLs are permitted. + * Permit HTTP (non-HTTPS) URLs. */ @Getter private final boolean allowHttp; /** - * RSA key size in bits. Always {@link Constants#RSA_KEY_SIZE}. + * RSA key size in bits ({@link Constants#RSA_KEY_SIZE}). */ @Getter private final int keySize; /** - * Maximum number of retries for retryable errors. + * Max retries on retryable errors. */ @Getter private final int maxRetries; /** - * Whether secure memory operations are active. + * Secure memory operations active. */ @Getter private final boolean useSecureMemory; @@ -88,38 +63,34 @@ public class SecureCompletionClient { private final ReentrantLock keyInitLock = new ReentrantLock(); /** - * RSA private key, or {@code null} if not yet loaded/generated. + * RSA private key ({@code null} until loaded/generated). */ @Getter private PrivateKey privateKey; - // ── Internal State ────────────────────────────────────────────── - /** - * PEM-encoded public key string, or {@code null} if not yet loaded/generated. + * PEM-encoded public key ({@code null} until loaded/generated). */ @Getter private String publicPemKey; /** - * Whether keys have been initialized. + * Keys initialized. */ private volatile boolean keysInitialized = false; /** - * Constructs a {@code SecureCompletionClient} with default settings. + * Default settings: {@code https://api.nomyo.ai}, HTTPS-only, secure memory, 2 retries. */ public SecureCompletionClient() { this(Constants.DEFAULT_BASE_URL, false, true, Constants.DEFAULT_MAX_RETRIES); } /** - * Constructs a {@code SecureCompletionClient} with the specified settings. - * - * @param routerUrl the NOMYO router base URL - * @param allowHttp whether to permit HTTP (non-HTTPS) URLs - * @param secureMemory whether to enable memory locking/zeroing - * @param maxRetries number of retries on retryable errors + * @param routerUrl NOMYO router base URL + * @param allowHttp permit HTTP URLs + * @param secureMemory enable memory locking/zeroing + * @param maxRetries retries on retryable errors */ public SecureCompletionClient(String routerUrl, boolean allowHttp, boolean secureMemory, int maxRetries) { this.routerUrl = routerUrl != null ? routerUrl.replaceAll("/+$", "") : Constants.DEFAULT_BASE_URL; @@ -129,33 +100,12 @@ public class SecureCompletionClient { this.maxRetries = maxRetries; } - // ── Key Management ────────────────────────────────────────────── - - private static String getEncryptedPrivateKeyFromFile(String privateKeyPath) { - File myObj = new File(privateKeyPath); - - StringBuilder builder = new StringBuilder(); - - try (Scanner myReader = new Scanner(myObj)) { - while (myReader.hasNextLine()) { - builder.append(myReader.nextLine()); - } - } catch (FileNotFoundException e) { - throw new RuntimeException("Tried to load private key from disk but no file found" + e.getMessage()); - } - - return builder.toString(); + private static String readFileContent(String filePath) throws IOException { + return Files.readString(Path.of(filePath)); } /** - * Generates a new 4096-bit RSA key pair. - * - *The public exponent is fixed at 65537. The generated key pair - * is stored in memory. Use {@code saveToDir} to persist to disk.
- * - * @param saveToFile whether to save the keys to disk - * @param keyDir directory to save keys (ignored if {@code saveToFile} is {@code false}) - * @param password optional password to encrypt the private key file + * Generates a 4096-bit RSA key pair (exponent 65537). Saves to disk if {@code saveToFile}. */ public void generateKeys(boolean saveToFile, String keyDir, String password) { try { @@ -167,10 +117,14 @@ public class SecureCompletionClient { String privatePem = PEMConverter.toPEM(pair.getPrivate().getEncoded(), true); String publicPem = PEMConverter.toPEM(pair.getPublic().getEncoded(), false); - if (saveToFile) { - File keyFolder = new File(keyDir); - if (!keyFolder.exists() && !keyFolder.mkdirs()) { - throw new IOException("Failed to create key directory: " + keyDir); + if (saveToFile) { + Path keyFolder = Path.of(keyDir); + if (!Files.exists(keyFolder)) { + try { + Files.createDirectories(keyFolder); + } catch (IOException e) { + throw new IOException("Failed to create key directory: " + keyDir, e); + } } Path privateKeyPath = Path.of(keyDir, Constants.DEFAULT_PRIVATE_KEY_FILE); @@ -178,7 +132,7 @@ public class SecureCompletionClient { SetIf {@code publicPemKeyPath} is {@code null}, the public key is - * derived from the loaded private key. Validates that the key size - * is at least {@link Constants#MIN_RSA_KEY_SIZE} bits.
- * - * @param privateKeyPath path to the private key PEM file - * @param publicPemKeyPath optional path to the public key PEM file - * @param password optional password for the encrypted private key + * @param privateKeyPath private key PEM path + * @param publicPemKeyPath optional public key PEM path + * @param password optional password for encrypted private key */ public void loadKeys(String privateKeyPath, String publicPemKeyPath, String password) { - File keyFile = new File(privateKeyPath); - if (!keyFile.exists()) { + Path keyPath = Path.of(privateKeyPath); + if (!Files.exists(keyPath)) { throw new RuntimeException("Private key file not found: " + privateKeyPath); } String keyContent; if (password != null && !password.isEmpty()) { - keyContent = getEncryptedPrivateKeyFromFile(privateKeyPath); + try { + keyContent = readFileContent(privateKeyPath); + } catch (IOException e) { + throw new RuntimeException("Failed to read private key file: " + e.getMessage(), e); + } try { keyContent = Pass2Key.decrypt("AES/GCM/NoPadding", keyContent, password); - } catch (NoSuchPaddingException | NoSuchAlgorithmException - | BadPaddingException | IllegalBlockSizeException | InvalidAlgorithmParameterException | - InvalidKeyException e) { + } catch (NoSuchPaddingException | NoSuchAlgorithmException | BadPaddingException | + IllegalBlockSizeException | InvalidAlgorithmParameterException | InvalidKeyException e) { System.out.println("Wrong password!"); return; } } else { - keyContent = getEncryptedPrivateKeyFromFile(privateKeyPath); + try { + keyContent = readFileContent(privateKeyPath); + } catch (IOException e) { + throw new RuntimeException("Failed to read private key file: " + e.getMessage(), e); + } } try { @@ -270,194 +222,108 @@ public class SecureCompletionClient { } /** - * Loads an RSA private key from disk, deriving the public key. - * - * @param privateKeyPath path to the private key PEM file - * @param password optional password for the encrypted private key + * Loads RSA private key from disk, deriving public key. */ public void loadKeys(String privateKeyPath, String password) { loadKeys(privateKeyPath, null, password); } - // ── Server Key Fetching ───────────────────────────────────────── - /** - * Fetches the server's RSA public key from the PKI endpoint. - * - *Performs a GET request to {@code {routerUrl}/pki/public_key} - * and returns the server PEM public key as a string. Validates that - * the response parses as a valid PEM public key.
- * - * @return the server's PEM-encoded public key string - * @throws SecurityError if the URL is not HTTPS and {@code allowHttp} is {@code false}, - * or if the response does not contain a valid PEM public key + * GET {@code {routerUrl}/pki/public_key}. Returns server PEM public key. */ public CompletableFutureSerializes the payload to JSON, then encrypts it using: - *
Headers: Content-Type=octet-stream, X-Payload-ID, X-Public-Key, Authorization (Bearer), X-Security-Tier. + * Retryable: 429, 500, 502, 503, 504 + network errors. Backoff: 2^(attempt-1)s. + *
Status mapping: 200→return, 400→InvalidRequestError, 401→AuthenticationError, 403→ForbiddenError, + * 404→APIError, 429→RateLimitError, 500→ServerError, 503→ServiceUnavailableError, + * 502/504→APIError(retryable), network→APIConnectionError. * - *
- * Content-Type: application/octet-stream
- * X-Payload-ID: {payloadId}
- * X-Public-Key: {urlEncodedPublicPemKey}
- * Authorization: Bearer {apiKey} (if apiKey is provided)
- * X-Security-Tier: {tier} (if securityTier is provided)
- *
- *
- * | Status | Result |
|---|---|
| 200 | Return decrypted response map |
| 400 | {@code InvalidRequestError} |
| 401 | {@code AuthenticationError} |
| 403 | {@code ForbiddenError} |
| 404 | {@code APIError} |
| 429 | {@code RateLimitError} |
| 500 | {@code ServerError} |
| 503 | {@code ServiceUnavailableError} |
| 502/504 | {@code APIError} (retryable) |
| other | {@code APIError} (non-retryable) |
| network error | {@code APIConnectionError} |
Uses double-checked locking via {@link ReentrantLock} to ensure - * thread-safe initialization. If {@code keyDir} is set, attempts to - * load keys from disk first; if that fails, generates new keys.
- * - * @param keyDir directory to persist keys, or {@code null} for ephemeral + * @param keyDir key directory or {@code null} for ephemeral */ public void ensureKeys(String keyDir) { if (keysInitialized) return; keyInitLock.lock(); try { if (keysInitialized) return; - // TODO: implement key loading/generation + if (keyDir == null || keyDir.isEmpty()) { + generateKeys(false); + } else { + generateKeys(true); + } keysInitialized = true; } finally { keyInitLock.unlock(); } } - // ── Key Validation ────────────────────────────────────────────── - /** - * Validates that an RSA key meets the minimum size requirement. - * - * @param key the RSA key to validate - * @throws SecurityError if the key size is less than {@link Constants#MIN_RSA_KEY_SIZE} bits + * Validates RSA key size >= {@link Constants#MIN_RSA_KEY_SIZE} bits. */ public void validateRsaKey(PrivateKey key) throws SecurityError { if (key == null) { @@ -466,77 +332,59 @@ public class SecureCompletionClient { int keySize = extractKeySize(key); if (keySize < Constants.MIN_RSA_KEY_SIZE) { - throw new SecurityError( - "RSA key size " + keySize + " bits is below minimum " + Constants.MIN_RSA_KEY_SIZE + " bits" - ); + throw new SecurityError("RSA key size " + keySize + " bits is below minimum " + Constants.MIN_RSA_KEY_SIZE + " bits"); } } private int extractKeySize(PrivateKey key) { try { - java.security.KeyFactory kf = java.security.KeyFactory.getInstance("RSA"); - java.security.spec.RSAPrivateCrtKeySpec crtSpec = kf.getKeySpec(key, java.security.spec.RSAPrivateCrtKeySpec.class); - return crtSpec.getModulus().bitLength(); - } catch (Exception ignored) { - // Try RSAPrivateKeySpec + var kf = KeyFactory.getInstance("RSA"); try { - java.security.KeyFactory kf = java.security.KeyFactory.getInstance("RSA"); - java.security.spec.RSAPrivateKeySpec privSpec = kf.getKeySpec(key, java.security.spec.RSAPrivateKeySpec.class); + var crtSpec = kf.getKeySpec(key, java.security.spec.RSAPrivateCrtKeySpec.class); + return crtSpec.getModulus().bitLength(); + } catch (Exception ignored) { + var privSpec = kf.getKeySpec(key, java.security.spec.RSAPrivateKeySpec.class); return privSpec.getModulus().bitLength(); - } catch (Exception ignored2) { - // Fall back to encoded length - if (key.getEncoded() != null) { - return key.getEncoded().length * 8; - } + } + } catch (Exception ignored) { + if (key.getEncoded() != null) { + return key.getEncoded().length * 8; } } return 0; } - // ── HTTP Status → Exception Mapping ───────────────────────────── - /** - * Maps an HTTP status code to the appropriate exception. + * Maps HTTP status code to exception (200→null). */ public Exception mapHttpStatus(int statusCode, String responseBody) { - switch (statusCode) { - case 200: - return null; - case 400: - return new InvalidRequestError("Invalid request: " + (responseBody != null ? responseBody : "no body")); - case 401: - return new AuthenticationError("Authentication failed: " + (responseBody != null ? responseBody : "no body")); - case 403: - return new ForbiddenError("Access forbidden: " + (responseBody != null ? responseBody : "no body")); - case 404: - return new APIError("Not found: " + (responseBody != null ? responseBody : "no body")); - case 429: - return new RateLimitError("Rate limit exceeded: " + (responseBody != null ? responseBody : "no body")); - case 500: - return new ServerError("Internal server error: " + (responseBody != null ? responseBody : "no body")); - case 503: - return new ServiceUnavailableError("Service unavailable: " + (responseBody != null ? responseBody : "no body")); - case 502: - case 504: - return new APIError("Gateway error: " + (responseBody != null ? responseBody : "no body")); - default: - return new APIError("Unexpected status " + statusCode + ": " + (responseBody != null ? responseBody : "no body")); - } + return switch (statusCode) { + case 200 -> null; + case 400 -> + new InvalidRequestError("Invalid request: " + (responseBody != null ? responseBody : "no body")); + case 401 -> + new AuthenticationError("Authentication failed: " + (responseBody != null ? responseBody : "no body")); + case 403 -> new ForbiddenError("Access forbidden: " + (responseBody != null ? responseBody : "no body")); + case 404 -> new APIError("Not found: " + (responseBody != null ? responseBody : "no body")); + case 429 -> new RateLimitError("Rate limit exceeded: " + (responseBody != null ? responseBody : "no body")); + case 500 -> new ServerError("Internal server error: " + (responseBody != null ? responseBody : "no body")); + case 503 -> + new ServiceUnavailableError("Service unavailable: " + (responseBody != null ? responseBody : "no body")); + case 502, 504 -> new APIError("Gateway error: " + (responseBody != null ? responseBody : "no body")); + default -> + new APIError("Unexpected status " + statusCode + ": " + (responseBody != null ? responseBody : "no body")); + }; } - // ── URL Encoding ──────────────────────────────────────────────── - /** - * URL-encodes a public key PEM string for use in the {@code X-Public-Key} header. + * URL-encodes PEM key for {@code X-Public-Key} header. */ public String urlEncodePublicKey(String pemKey) { return java.net.URLEncoder.encode(pemKey, StandardCharsets.UTF_8); } - // ── Getters ───────────────────────────────────────────────────── - /** - * Closes the client and releases any resources. + * Delegates to resource cleanup (stub). */ public void close() { throw new UnsupportedOperationException("Not yet implemented"); diff --git a/src/main/java/ai/nomyo/SecureMemory.java b/src/main/java/ai/nomyo/SecureMemory.java index e16d7fc..ee94d3e 100644 --- a/src/main/java/ai/nomyo/SecureMemory.java +++ b/src/main/java/ai/nomyo/SecureMemory.java @@ -8,43 +8,22 @@ import java.lang.foreign.MemorySegment; import java.util.Map; /** - * Cross-platform memory locking and secure zeroing utilities. - * - *This module provides optional memory protection for sensitive - * cryptographic buffers. It fails gracefully if memory locking is - * unavailable on the current platform (e.g., Windows on some JVM - * configurations).
- * - *{@code
- * try (SecureBuffer buf = SecureMemory.secureBytearray(sensitiveData)) {
- * // buf is locked and ready to use
- * process(buf.getData());
- * }
- * // buf is automatically zeroed and unlocked on exit
- * }
+ * Cross-platform memory locking and secure zeroing for sensitive cryptographic buffers. Fails gracefully if unavailable.
*/
public final class SecureMemory {
- @Getter
- @Setter
- private static volatile boolean secureMemoryEnabled = true;
-
@Getter
private static final boolean HAS_MEMORY_LOCKING;
@Getter
private static final boolean HAS_SECURE_ZEROING;
+ @Getter
+ @Setter
+ private static volatile boolean secureMemoryEnabled = true;
static {
boolean locking = false;
boolean zeroing = false;
+
try {
locking = initMemoryLocking();
zeroing = true; // Secure zeroing is always available at the JVM level
@@ -58,16 +37,59 @@ public final class SecureMemory {
private static boolean initMemoryLocking() {
// FFM doesn't support memory locking at this point in time
- // TODO: Bypass this with native libraries
return false;
}
/**
- * Wraps a byte array with memory locking and guaranteed zeroing on exit.
- *
- * Implements {@link AutoCloseable} for use with try-with-resources. - * The buffer is automatically zeroed and unlocked when closed, even - * if an exception occurs.
+ * Recommended way to handle sensitive data — use within try-with-resources for secure zeroing. + */ + public static SecureBuffer secureByteArray(byte[] data, boolean lock) { + return new SecureBuffer(data, lock); + } + + /** + * Always attempts locking. + */ + public static SecureBuffer secureByteArray(byte[] data) { + return secureByteArray(data, true); + } + + /** + * @deprecated Use {@link #secureByteArray(byte[])} instead. + */ + @Deprecated + public static SecureBuffer secureBytes(byte[] data, boolean lock) { + return new SecureBuffer(data, lock); + } + + /** + * @deprecated Use {@link #secureByteArray(byte[])} instead. + */ + @Deprecated + public static SecureBuffer secureBytes(byte[] data) { + return secureBytes(data, true); + } + + /** + * Returns protection capabilities: enabled, protection_level, has_memory_locking, has_secure_zeroing, supports_full_protection, page_size. + */ + public static MapThis is the recommended way to handle sensitive data. The returned - * buffer should be used within a try-with-resources block to ensure - * secure zeroing on exit.
- * - * @param data the sensitive data bytes - * @param lock whether to attempt memory locking - * @return a new SecureBuffer - */ - public static SecureBuffer secureByteArray(byte[] data, boolean lock) { - return new SecureBuffer(data, lock); - } - - /** - * Creates a SecureBuffer for the given data with memory locking. - * Convenience variant that always attempts locking. - * - * @param data the sensitive data bytes - * @return a new SecureBuffer - */ - public static SecureBuffer secureByteArray(byte[] data) { - return secureByteArray(data, true); - } - - /** - * Creates a SecureBuffer for the given data with memory locking. - * - *Deprecated: Use {@link #secureByteArray(byte[])} instead. - * This method exists for compatibility with the Python reference.
- * - * @param data the sensitive data bytes - * @param lock whether to attempt memory locking - * @return a new SecureBuffer - * @deprecated Use {@link #secureByteArray(byte[])} instead - */ - @Deprecated - public static SecureBuffer secureBytes(byte[] data, boolean lock) { - return new SecureBuffer(data, lock); - } - - /** - * Creates a SecureBuffer for the given data with memory locking. - * - *Deprecated: Use {@link #secureByteArray(byte[])} instead. - * This method exists for compatibility with the Python reference.
- * - * @param data the sensitive data bytes - * @return a new SecureBuffer - * @deprecated Use {@link #secureByteArray(byte[])} instead - */ - @Deprecated - public static SecureBuffer secureBytes(byte[] data) { - return secureBytes(data, true); - } - - /** - * Returns information about the current memory protection capabilities. - * - * @return a map of protection capabilities - */ - public static MapThis includes connection timeouts, DNS resolution failures, - * TLS handshake failures, and other network-level errors. Unlike - * {@link APIError}, this exception does not carry an HTTP status code.
- */ +/** Network-level errors: timeouts, DNS failures, TLS handshake failures. No HTTP status code. */ public class APIConnectionError extends Exception { - /** - * Constructs an {@code APIConnectionError} with the specified detail message. - * - * @param message the detail message - */ public APIConnectionError(String message) { super(message); } - /** - * Constructs an {@code APIConnectionError} with the specified detail message - * and cause. - * - * @param message the detail message - * @param cause the cause of this exception, or {@code null} - */ public APIConnectionError(String message, Throwable cause) { super(message, cause); } - /** - * Constructs an {@code APIConnectionError} with the specified cause. - * - * @param cause the cause of this exception - */ public APIConnectionError(Throwable cause) { super(cause); } diff --git a/src/main/java/ai/nomyo/errors/APIError.java b/src/main/java/ai/nomyo/errors/APIError.java index df4dc36..801bd9d 100644 --- a/src/main/java/ai/nomyo/errors/APIError.java +++ b/src/main/java/ai/nomyo/errors/APIError.java @@ -1,26 +1,23 @@ package ai.nomyo.errors; +import lombok.Getter; + import java.util.Collections; import java.util.Map; -/** - * Base exception for all NOMYO API errors. - * - *All API error subclasses carry a {@code status_code} and optional - * {@code error_details} from the server response.
- */ +/** Base exception for all NOMYO API errors. Carries HTTP status code and optional error details. */ +@Getter public class APIError extends Exception { + /** HTTP status code ({@code null} if not applicable). */ private final Integer statusCode; + /** Unmodifiable map of error details from server (never {@code null}). */ private final MapUnlike {@link APIError}, this exception carries no HTTP status code. - * It is used for issues such as invalid key sizes, encryption/decryption - * failures, and missing keys.
- * - *Any decryption failure (except JSON parse errors) raises - * {@code SecurityError("Decryption failed: integrity check or authentication failed")}.
- */ +/** Cryptographic and key-related failures. No HTTP status code. */ public class SecurityError extends Exception { - /** - * Constructs a {@code SecurityError} with the specified detail message. - * - * @param message the detail message - */ public SecurityError(String message) { super(message); } - /** - * Constructs a {@code SecurityError} with the specified detail message - * and cause. - * - * @param message the detail message - * @param cause the underlying cause, or {@code null} - */ public SecurityError(String message, Throwable cause) { super(message, cause); } diff --git a/src/main/java/ai/nomyo/errors/ServerError.java b/src/main/java/ai/nomyo/errors/ServerError.java index 55415c1..b94f659 100644 --- a/src/main/java/ai/nomyo/errors/ServerError.java +++ b/src/main/java/ai/nomyo/errors/ServerError.java @@ -2,39 +2,17 @@ package ai.nomyo.errors; import java.util.Map; -/** - * Exception thrown when the API returns a 500 (Internal Server Error) status. - */ +/** HTTP 500 (Internal Server Error). */ public class ServerError extends APIError { - /** - * Constructs a {@code ServerError} with the specified detail message, - * status code, and error details. - * - * @param message the detail message - * @param statusCode the HTTP status code (must be 500) - * @param errorDetails additional error details from the server, or {@code null} - */ public ServerError(String message, Integer statusCode, MapThe encrypted output format stores salt + IV + ciphertext in that order, - * all base64-encoded. This ensures the salt and IV are persisted alongside - * the ciphertext for decryption.
- * - *- * [ 16 bytes salt ][ 12 bytes IV ][ variable bytes ciphertext ] - *+ * Password-based encryption: PBKDF2 key derivation + AES-GCM. Output: base64(salt[16] + IV[12] + ciphertext). */ public final class Pass2Key { @@ -36,7 +28,8 @@ public final class Pass2Key { private static final int GCM_TAG_LENGTH = 128; private static final int ITERATION_COUNT = 65536; - private Pass2Key() {} + private Pass2Key() { + } /** * Encrypts the given plaintext using the specified algorithm and password. @@ -46,10 +39,7 @@ public final class Pass2Key { * @param password the password used to derive the encryption key * @return base64-encoded ciphertext including salt and IV */ - public static String encrypt(String algorithm, String input, String password) - throws NoSuchPaddingException, NoSuchAlgorithmException, - InvalidAlgorithmParameterException, InvalidKeyException, - BadPaddingException, IllegalBlockSizeException { + public static String encrypt(String algorithm, String input, String password) throws NoSuchPaddingException, NoSuchAlgorithmException, InvalidAlgorithmParameterException, InvalidKeyException, BadPaddingException, IllegalBlockSizeException { byte[] salt = generateRandomBytes(SALT_LENGTH); SecretKey key = deriveKey(password, salt); @@ -76,10 +66,7 @@ public final class Pass2Key { * @param password the password used to derive the decryption key * @return the decrypted plaintext */ - public static String decrypt(String algorithm, String cipherText, String password) - throws NoSuchPaddingException, NoSuchAlgorithmException, - InvalidAlgorithmParameterException, InvalidKeyException, - BadPaddingException, IllegalBlockSizeException { + public static String decrypt(String algorithm, String cipherText, String password) throws NoSuchPaddingException, NoSuchAlgorithmException, InvalidAlgorithmParameterException, InvalidKeyException, BadPaddingException, IllegalBlockSizeException { byte[] decoded = Base64.getDecoder().decode(cipherText); @@ -99,8 +86,6 @@ public final class Pass2Key { } } - // ── Key Derivation ──────────────────────────────────────────────── - private static SecretKey deriveKey(String password, byte[] salt) { try { SecretKeyFactory factory = SecretKeyFactory.getInstance("PBKDF2WithHmacSHA256"); @@ -111,50 +96,32 @@ public final class Pass2Key { } } - // ── Cipher Operations ───────────────────────────────────────────── - - private static byte[] encryptWithCipher(String algorithm, SecretKey key, - GCMParameterSpec spec, String input) - throws NoSuchPaddingException, NoSuchAlgorithmException, - InvalidAlgorithmParameterException, InvalidKeyException, - BadPaddingException, IllegalBlockSizeException { + private static byte[] encryptWithCipher(String algorithm, SecretKey key, GCMParameterSpec spec, String input) throws NoSuchPaddingException, NoSuchAlgorithmException, InvalidAlgorithmParameterException, InvalidKeyException, BadPaddingException, IllegalBlockSizeException { Cipher cipher = Cipher.getInstance(algorithm); cipher.init(Cipher.ENCRYPT_MODE, key, spec); - return cipher.doFinal(input.getBytes()); + return cipher.doFinal(input.getBytes(StandardCharsets.UTF_8)); } - private static byte[] encryptWithCipher(String algorithm, SecretKey key, String input) - throws NoSuchPaddingException, NoSuchAlgorithmException, - InvalidAlgorithmParameterException, InvalidKeyException, - BadPaddingException, IllegalBlockSizeException { + private static byte[] encryptWithCipher(String algorithm, SecretKey key, String input) throws NoSuchPaddingException, NoSuchAlgorithmException, InvalidKeyException, BadPaddingException, IllegalBlockSizeException { Cipher cipher = Cipher.getInstance(algorithm); cipher.init(Cipher.ENCRYPT_MODE, key); - return cipher.doFinal(input.getBytes()); + return cipher.doFinal(input.getBytes(StandardCharsets.UTF_8)); } - private static String decryptWithCipher(String algorithm, SecretKey key, - GCMParameterSpec spec, byte[] ciphertext) - throws NoSuchPaddingException, NoSuchAlgorithmException, - InvalidAlgorithmParameterException, InvalidKeyException, - BadPaddingException, IllegalBlockSizeException { + private static String decryptWithCipher(String algorithm, SecretKey key, GCMParameterSpec spec, byte[] ciphertext) throws NoSuchPaddingException, NoSuchAlgorithmException, InvalidAlgorithmParameterException, InvalidKeyException, BadPaddingException, IllegalBlockSizeException { Cipher cipher = Cipher.getInstance(algorithm); cipher.init(Cipher.DECRYPT_MODE, key, spec); byte[] plaintext = cipher.doFinal(ciphertext); - return new String(plaintext); + return new String(plaintext, StandardCharsets.UTF_8); } - private static String decryptWithCipher(String algorithm, SecretKey key, byte[] ciphertext) - throws NoSuchPaddingException, NoSuchAlgorithmException, - InvalidAlgorithmParameterException, InvalidKeyException, - BadPaddingException, IllegalBlockSizeException { + private static String decryptWithCipher(String algorithm, SecretKey key, byte[] ciphertext) throws NoSuchPaddingException, NoSuchAlgorithmException, InvalidKeyException, BadPaddingException, IllegalBlockSizeException { Cipher cipher = Cipher.getInstance(algorithm); cipher.init(Cipher.DECRYPT_MODE, key); byte[] plaintext = cipher.doFinal(ciphertext); - return new String(plaintext); + return new String(plaintext, StandardCharsets.UTF_8); } - // ── Helpers ─────────────────────────────────────────────────────── - private static boolean isGcmMode(String algorithm) { return algorithm.contains("GCM"); } @@ -183,9 +150,7 @@ public final class Pass2Key { public static PrivateKey convertStringToPrivateKey(String privateKeyString) throws Exception { // Remove any header and footer information if present - privateKeyString = privateKeyString.replace("-----BEGIN PRIVATE KEY-----", "") - .replace("-----END PRIVATE KEY-----", "") - .replaceAll("\\s+", ""); + privateKeyString = privateKeyString.replace("-----BEGIN PRIVATE KEY-----", "").replace("-----END PRIVATE KEY-----", "").replaceAll("\\s+", ""); // Decode the Base64-encoded private key string byte[] decodedKey = Base64.getDecoder().decode(privateKeyString); diff --git a/src/main/java/ai/nomyo/util/Splitter.java b/src/main/java/ai/nomyo/util/Splitter.java index 47f4dec..4f80b3e 100644 --- a/src/main/java/ai/nomyo/util/Splitter.java +++ b/src/main/java/ai/nomyo/util/Splitter.java @@ -4,34 +4,22 @@ import java.util.ArrayList; import java.util.List; /** - * @author NieGestorben - * Copyright© (c) 2026, All Rights Reserved. + * Splits a string into fixed-length substrings. */ public class Splitter { + /** + * Splits {@code toSplit} into substrings of at most {@code length} characters. + */ public static List