nomyo4J — Agent Instructions

Java port of the NOMYO Python client. Hybrid encryption (RSA-4096 + AES-256-GCM) for secure API communication.

Build & Run

mvn compile          # Java 25, Lombok annotation processor
mvn test             # JUnit Jupiter 5.12.1, @Order enforced
mvn test -Dtest=ClassName   # single test class

Architecture

SecureCompletionClient — low-level client: key mgmt, HTTP, encryption, decryption
SecureChatCompletion — high-level OpenAI-compatible surface (create(), acreate())
Constants — all protocol/crypto constants (version, algorithms, timeouts)
SecureMemory — Java 25 FFM SecureBuffer for locked/zeroed memory
errors/ — exception hierarchy, all extends Exception (checked)
util/ — Pass2Key (PBKDF2 + AES-GCM), PEMConverter, Splitter

Critical: This is a partial/in-progress port

Many methods are stubbed with UnsupportedOperationException. Before implementing, check TRANSLATION_REFERENCE.md for the Python reference. Stubbed methods:

SecureCompletionClient.fetchServerPublicKey() — GET /pki/public_key
SecureCompletionClient.encryptPayload() / doEncrypt() — hybrid encryption
SecureCompletionClient.decryptResponse() — response decryption
SecureCompletionClient.sendSecureRequest() (3 overloads) — full request lifecycle
SecureCompletionClient.ensureKeys() — key init (partial DCL implemented)
SecureCompletionClient.close() — resource cleanup
SecureChatCompletion.create() / acreate() — return null, stubbed
SecureMemory lock/unlock — always returns false

No JSON library (Jackson/Gson) in pom.xml — needed for wire format serialization.

Key files

TRANSLATION_REFERENCE.md — primary documentation. Cross-language spec derived from Python reference. Read before implementing any method.
client_keys/ — contains real RSA keys. Gitignored. Do not commit.
Main.java — entry point is static void main() — not public static void main(String[]). Cannot run standalone.

Conventions

Package: ai.nomyo
Lombok: @Getter on fields, @Setter on static flags
Tests: @TestMethodOrder(OrderAnnotation.class), @DisplayName on every test
Error classes: checked exceptions with status_code and error_details
Key files: PosixFilePermissions.OWNER_READ only (mode 400)
RSA: 4096-bit, exponent 65537, OAEP-SHA256 padding
Protocol constants in Constants.java — marked "never change"

2.5 KiB Raw Blame History