# 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"