52 lines
2.5 KiB
Markdown
52 lines
2.5 KiB
Markdown
|
# 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"
|