nomyo-js/doc/api-reference.md

# API Reference

## `SecureChatCompletion`

High-level OpenAI-compatible client. The recommended entry point for most use cases.

### Constructor

```typescript
new SecureChatCompletion(config?: ChatCompletionConfig)
```

#### `ChatCompletionConfig`


| Option                | Type      | Default                  | Description                                                                                                                                                               |
| ----------------------- | ----------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `baseUrl`             | `string`  | `'https://api.nomyo.ai'` | NOMYO router URL. Must be HTTPS in production.                                                                                                                            |
| `allowHttp`           | `boolean` | `false`                  | Allow HTTP connections.**Local development only.**                                                                                                                        |
| `apiKey`              | `string`  | `undefined`              | Bearer token sent in`Authorization` header.                                                                                                                               |
| `secureMemory`        | `boolean` | `true`                   | Enable immediate zeroing of sensitive buffers after use.                                                                                                                  |
| `timeout`             | `number`  | `900000` (15 min)        | Request timeout in milliseconds. Encrypted inference cannot stream, so the whole completion arrives in one response; long generations legitimately take minutes.           |
| `debug`               | `boolean` | `false`                  | Print verbose logging to the console.                                                                                                                                     |
| `keyDir`              | `string \| null` | `null`            | Directory to load/save RSA keys on startup. If the directory contains an existing key pair it is loaded; otherwise a new pair is generated and saved there. Omit (or pass `null`) for ephemeral keys generated in memory for this session only and never written to disk — this is the default, matching the Python SDK. Node.js only; browsers are always ephemeral. |
| `keyRotationInterval` | `number`  | `86400000` (24 h)        | Auto-rotate RSA keys every N milliseconds. Set to`0` to disable.                                                                                                          |
| `keyRotationDir`      | `string`  | value of `keyDir`        | Directory where rotated key files are saved. When neither this nor `keyDir` is set, rotated keys stay in memory. Node.js only.                                             |
| `keyRotationPassword` | `string`  | `undefined`              | Password used to encrypt rotated key files.                                                                                                                               |
| `maxRetries`          | `number`  | `2`                      | Maximum extra attempts on retryable errors (429, 500, 502, 503, 504, network errors). Uses exponential backoff (1 s, 2 s, …). Set to`0` to disable retries.              |
| `attestationPolicy`   | `AttestationPolicy` | `undefined`    | Enables SGX attestation verification before any plaintext is sent. Omit to disable. See [Attestation](attestation.md).                                                     |
| `quoteVerifier`       | `QuoteVerifier` | `undefined`        | Performs the DCAP quote verification (e.g.`JwtQuoteVerifier`). Required for a policy to actually verify; without one, a set policy treats attestation as unverifiable.   |

### Methods

#### `create(request): Promise<ChatCompletionResponse>`

Send an encrypted chat completion request. Returns the decrypted response.

```typescript
async create(request: ChatCompletionRequest): Promise<ChatCompletionResponse>
```

**`ChatCompletionRequest` fields:**


| Field               | Type                     | Description                                                                                                                    |
| --------------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `model`             | `string`                 | **Required.** Model ID (see [Models](models.md)).                                                                              |
| `messages`          | `Message[]`              | **Required.** Conversation history.                                                                                            |
| `temperature`       | `number`                 | Sampling temperature (0–2).                                                                                                   |
| `top_p`             | `number`                 | Nucleus sampling.                                                                                                              |
| `max_tokens`        | `number`                 | Maximum tokens to generate.                                                                                                    |
| `stop`              | `string | string[]`      | Stop sequences.                                                                                                                |
| `n`                 | `number`                 | Number of completions to generate.                                                                                             |
| `stream`            | `boolean`                | Ignored server-side (encryption requires full response).                                                                       |
| `presence_penalty`  | `number`                 | Presence penalty (−2.0–2.0).                                                                                                 |
| `frequency_penalty` | `number`                 | Frequency penalty (−2.0–2.0).                                                                                                |
| `logit_bias`        | `Record<string, number>` | Token bias map.                                                                                                                |
| `user`              | `string`                 | End-user identifier (passed through).                                                                                          |
| `tools`             | `Tool[]`                 | Tool/function definitions.                                                                                                     |
| `tool_choice`       | `ToolChoice`             | Tool selection strategy (`"auto"`, `"none"`, `"required"`, or specific tool).                                                  |
| `security_tier`     | `string`                 | NOMYO-specific.`"standard"` \| `"high"` \| `"maximum"`. Not encrypted into the payload.                                        |
| `api_key`           | `string`                 | NOMYO-specific. Per-request API key override. Not encrypted into the payload.                                                  |
| `base_url`          | `string`                 | NOMYO-specific. Per-request router URL override. Creates a temporary client for this one call. Not encrypted into the payload. |

**Response shape (`ChatCompletionResponse`):**

```typescript
{
  id: string;
  object: 'chat.completion';
  created: number;
  model: string;
  choices: Array<{
    index: number;
    message: {
      role: string;
      content: string;
      tool_calls?: ToolCall[];       // present if tools were invoked
      reasoning_content?: string;   // chain-of-thought (Qwen3, DeepSeek-R1, etc.)
    };
    finish_reason: 'stop' | 'length' | 'tool_calls' | 'content_filter' | null;
  }>;
  usage?: {
    prompt_tokens: number;
    completion_tokens: number;
    total_tokens: number;
  };
  _metadata?: {
    payload_id: string;           // echoes the X-Payload-ID sent with the request
    processed_at: number;         // Unix timestamp of server-side processing
    is_encrypted: boolean;        // always true for this endpoint
    encryption_algorithm: string; // e.g. "hybrid-aes256-rsa4096"
    response_status: string;      // "success" on success
    security_tier?: string;       // active tier used by the server
    memory_protection?: {
      platform: string;
      memory_locking: boolean;
      secure_zeroing: boolean;
      core_dump_prevention: boolean;
    };
    cuda_device?: {
      available: boolean;
      device_hash: string;        // SHA-256 of device name (not the raw name)
    };
  };
}
```

#### `acreate(request): Promise<ChatCompletionResponse>`

Alias for `create()`. Provided for code that follows the OpenAI SDK naming convention.

#### `dispose(): void`

Stop the key-rotation timer and sever in-memory RSA key references so they can be garbage-collected. After calling `dispose()`, all methods throw `DisposedError`.

```javascript
client.dispose();
```

---

## `SecureCompletionClient`

Lower-level client that exposes key management and individual encryption/decryption operations.
Use this when you need fine-grained control; for most use cases prefer `SecureChatCompletion`.

### Constructor

```typescript
new SecureCompletionClient(config?: ClientConfig)
```

#### `ClientConfig`

All options from `ChatCompletionConfig`, plus:


| Option      | Type          | Default                        | Description                                                   |
| ------------- | --------------- | -------------------------------- | --------------------------------------------------------------- |
| `routerUrl` | `string`      | `'https://api.nomyo.ai'`       | NOMYO router base URL.                                        |
| `keySize`   | `2048 | 4096` | `4096`                         | RSA modulus length. 2048 is accepted but 4096 is recommended. |

(`baseUrl` is renamed to `routerUrl` at this level; all other options are identical.)

### Methods

#### `generateKeys(options?): Promise<void>`

Generate a fresh RSA key pair.

```typescript
await client.generateKeys({
  keySize?: 2048 | 4096,     // default: 4096
  saveToFile?: boolean,      // default: false
  keyDir?: string,           // default: 'client_keys'
  password?: string,         // minimum 8 characters if provided
});
```

#### `loadKeys(privateKeyPath, publicKeyPath?, password?): Promise<void>`

Load an existing key pair from PEM files. Node.js only.

```typescript
await client.loadKeys(
  'client_keys/private_key.pem',
  'client_keys/public_key.pem',  // optional; derived from private key path if omitted
  'your-password'                // required if private key is encrypted
);
```

#### `fetchServerPublicKey(): Promise<string>`

Fetch the server's RSA public key from `/pki/public_key` over HTTPS. Called automatically on every encryption; exposed for diagnostics.

#### `encryptPayload(payload): Promise<ArrayBuffer>`

Encrypt a request payload. Returns the encrypted binary package ready to POST.

#### `decryptResponse(encrypted, payloadId): Promise<object>`

Decrypt a response body received from the secure endpoint.

#### `sendSecureRequest(payload, payloadId, apiKey?, securityTier?): Promise<object>`

Full encrypt → POST → decrypt cycle with retry logic. Called internally by `SecureChatCompletion.create()`.

#### `dispose(): void`

Same as `SecureChatCompletion.dispose()`.

---

## Secure Memory API

```typescript
import {
  getMemoryProtectionInfo,
  disableSecureMemory,
  enableSecureMemory,
  SecureByteContext,
} from 'nomyo-js';
```

### `getMemoryProtectionInfo(): ProtectionInfo`

Returns information about the memory protection available on the current platform:

```typescript
interface ProtectionInfo {
  canLock: boolean;       // true if mlock is available (requires native addon)
  isPlatformSecure: boolean;
  method: 'mlock' | 'zero-only' | 'none';
  details?: string;
}
```

### `disableSecureMemory(): void`

Disable secure-memory zeroing globally. Affects new `SecureByteContext` instances that do not pass an explicit `useSecure` argument. Existing client instances are unaffected (they pass `useSecure` explicitly).

### `enableSecureMemory(): void`

Re-enable secure memory operations globally.

### `SecureByteContext`

Low-level context manager that zeros an `ArrayBuffer` in a `finally` block even if an exception occurs. Analogous to Python's `secure_bytearray()` context manager.

```typescript
const context = new SecureByteContext(sensitiveBuffer);
const result = await context.use(async (data) => {
  return doSomethingWith(data);
});
// sensitiveBuffer is zeroed here regardless of whether doSomethingWith threw
```

---

## Error Classes

All errors are exported from the package root.

```typescript
import {
  APIError,
  AuthenticationError,
  InvalidRequestError,
  RateLimitError,
  ForbiddenError,
  ServerError,
  ServiceUnavailableError,
  APIConnectionError,
  SecurityError,
  AttestationError,
  DisposedError,
} from 'nomyo-js';
```


| Class                     | HTTP status | Thrown when                                                  |
| --------------------------- | ------------- | -------------------------------------------------------------- |
| `AuthenticationError`     | 401         | Invalid or missing API key                                   |
| `InvalidRequestError`     | 400         | Malformed request (e.g. streaming requested)                 |
| `ForbiddenError`          | 403         | Model not allowed for the requested security tier            |
| `RateLimitError`          | 429         | Rate limit exceeded (after all retries exhausted)            |
| `ServerError`             | 500         | Internal server error (after all retries exhausted)          |
| `ServiceUnavailableError` | 503         | Inference backend unavailable (after all retries exhausted)  |
| `APIError`                | varies      | Other HTTP errors (404, 502, 504, etc.)                      |
| `APIConnectionError`      | —          | Network failure or timeout (after all retries exhausted)     |
| `SecurityError`           | —          | HTTPS not used, header injection detected, or crypto failure |
| `AttestationError`        | —          | SGX attestation failed under`enforce` (extends `SecurityError`) |
| `DisposedError`           | —          | Method called after`dispose()`                               |

All errors that extend `APIError` expose `statusCode?: number` and `errorDetails?: object`.

### Malformed data vs security failures

A plain `Error` — not a `SecurityError` — is thrown when a response is
structurally wrong rather than cryptographically suspect: a missing package
field, an unsupported protocol version, a non-200 or unparseable
`/pki/public_key` response, or plaintext that decrypted and authenticated
successfully but is not valid JSON.

`SecurityError` is reserved for actual security conditions, and stays
deliberately vague about which stage failed so it cannot be used as a decryption
oracle:

```typescript
try {
  await client.create({ model, messages });
} catch (error) {
  if (error instanceof SecurityError) {
    // integrity/authentication failure, HTTPS violation, or failed attestation
  } else if (error instanceof APIError) {
    // server responded with an HTTP error
  } else {
    // malformed response data
  }
}
```

This mirrors the Python SDK, which raises `ValueError` where this client throws
a plain `Error`.