@simplysm/service-server 14.0.4 → 14.0.5

package/README.md

@@ -1,63 +1,133 @@
 # @simplysm/service-server
 
-Service server framework -- Fastify-based RPC server with WebSocket support, JWT authentication, service definitions, file upload/download, and built-in ORM/auto-update services.
-
-Depends on `@simplysm/service-common` for shared protocol and types.
-
-## API
-
-| Export | Kind | Category | Docs |
-|--------|------|----------|------|
-| `ServiceServerOptions` | interface | Types | [docs/types.md](docs/types.md) |
-| `AuthTokenPayload` | interface | Auth | [docs/auth.md](docs/auth.md) |
-| `signJwt` | function | Auth | [docs/auth.md](docs/auth.md) |
-| `verifyJwt` | function | Auth | [docs/auth.md](docs/auth.md) |
-| `decodeJwt` | function | Auth | [docs/auth.md](docs/auth.md) |
-| `ServiceContext` | interface | Core | [docs/core.md](docs/core.md) |
-| `createServiceContext` | function | Core | [docs/core.md](docs/core.md) |
-| `getServiceAuthPermissions` | function | Core | [docs/core.md](docs/core.md) |
-| `auth` | function | Core | [docs/core.md](docs/core.md) |
-| `ServiceDefinition` | interface | Core | [docs/core.md](docs/core.md) |
-| `defineService` | function | Core | [docs/core.md](docs/core.md) |
-| `ServiceMethods` | type | Core | [docs/core.md](docs/core.md) |
-| `executeServiceMethod` | function | Core | [docs/core.md](docs/core.md) |
-| `WebSocketHandler` | interface | Transport | [docs/transport.md](docs/transport.md) |
-| `createWebSocketHandler` | function | Transport | [docs/transport.md](docs/transport.md) |
-| `ServiceSocket` | interface | Transport | [docs/transport.md](docs/transport.md) |
-| `createServiceSocket` | function | Transport | [docs/transport.md](docs/transport.md) |
-| `handleHttpRequest` | function | Transport | [docs/transport.md](docs/transport.md) |
-| `handleUpload` | function | Transport | [docs/transport.md](docs/transport.md) |
-| `handleStaticFile` | function | Transport | [docs/transport.md](docs/transport.md) |
-| `ServerProtocolWrapper` | interface | Protocol | [docs/protocol.md](docs/protocol.md) |
-| `createServerProtocolWrapper` | function | Protocol | [docs/protocol.md](docs/protocol.md) |
-| `OrmService` | const | Services | [docs/services.md](docs/services.md) |
-| `OrmServiceType` | type | Services | [docs/services.md](docs/services.md) |
-| `AutoUpdateService` | const | Services | [docs/services.md](docs/services.md) |
-| `AutoUpdateServiceType` | type | Services | [docs/services.md](docs/services.md) |
-| `getConfig` | function | Utilities | [docs/utilities.md](docs/utilities.md) |
-| `handleV1Connection` | function | Legacy | [docs/legacy.md](docs/legacy.md) |
-| `ServiceServer` | class | Main | [docs/main.md](docs/main.md) |
-| `createServiceServer` | function | Main | [docs/main.md](docs/main.md) |
-
-## Usage
+Fastify-based RPC server with WebSocket support, JWT authentication, service definitions, file upload/download, static file serving, and built-in ORM/auto-update services. Depends on `@simplysm/service-common` for shared protocol and types.
+
+## Installation
+
+```bash
+npm install @simplysm/service-server
+```
+
+## API Overview
+
+### Server Options
+| API | Type | Description |
+|-----|------|-------------|
+| `ServiceServerOptions` | `interface` | Server configuration (rootPath, port, SSL, auth, services) |
+
+-> See [docs/server-options.md](./docs/server-options.md) for details.
+
+### Authentication (JWT)
+| API | Type | Description |
+|-----|------|-------------|
+| `AuthTokenPayload` | `interface` | JWT token payload with roles and custom data |
+| `signJwt` | `function` | Signs a JWT token (HS256, 12h expiry) |
+| `verifyJwt` | `function` | Verifies a JWT token |
+| `decodeJwt` | `function` | Decodes a JWT token without verification |
+
+-> See [docs/auth.md](./docs/auth.md) for details.
+
+### Service Definition/Context
+| API | Type | Description |
+|-----|------|-------------|
+| `ServiceContext` | `interface` | Service execution context (server, socket, auth, config) |
+| `createServiceContext` | `function` | Creates a service context instance |
+| `getServiceAuthPermissions` | `function` | Reads auth permissions from an auth-wrapped function |
+| `auth` | `function` | Authentication wrapper for service factories and methods |
+| `ServiceDefinition` | `interface` | Service definition with name and factory |
+| `defineService` | `function` | Defines a named service with a factory function |
+| `ServiceMethods` | `type` | Extracts method signatures from a ServiceDefinition |
+
+-> See [docs/service-definition.md](./docs/service-definition.md) for details.
+
+### Service Executor
+| API | Type | Description |
+|-----|------|-------------|
+| `executeServiceMethod` | `function` | Executes a service method with auth checking |
+
+-> See [docs/service-executor.md](./docs/service-executor.md) for details.
+
+### WebSocket Handler
+| API | Type | Description |
+|-----|------|-------------|
+| `WebSocketHandler` | `interface` | Multi-connection WebSocket handler with event broadcasting |
+| `createWebSocketHandler` | `function` | Creates a WebSocket handler instance |
+
+-> See [docs/websocket-handler.md](./docs/websocket-handler.md) for details.
+
+### Service Socket
+| API | Type | Description |
+|-----|------|-------------|
+| `ServiceSocket` | `interface` | Single WebSocket connection with protocol and events |
+| `createServiceSocket` | `function` | Creates a service socket instance |
+
+-> See [docs/service-socket.md](./docs/service-socket.md) for details.
+
+### HTTP Handlers
+| API | Type | Description |
+|-----|------|-------------|
+| `handleHttpRequest` | `function` | Handles HTTP RPC requests (GET/POST) |
+| `handleUpload` | `function` | Handles multipart file uploads |
+| `handleStaticFile` | `function` | Serves static files with security guards |
+
+-> See [docs/http-handlers.md](./docs/http-handlers.md) for details.
+
+### Protocol Wrapper
+| API | Type | Description |
+|-----|------|-------------|
+| `ServerProtocolWrapper` | `interface` | Server-side protocol wrapper with worker thread offloading |
+| `createServerProtocolWrapper` | `function` | Creates a server protocol wrapper instance |
+
+-> See [docs/protocol-wrapper.md](./docs/protocol-wrapper.md) for details.
+
+### ORM/AutoUpdate Services
+| API | Type | Description |
+|-----|------|-------------|
+| `OrmService` | `const (ServiceDefinition)` | Built-in ORM service definition |
+| `OrmServiceType` | `type` | ORM service method signatures |
+| `AutoUpdateService` | `const (ServiceDefinition)` | Built-in auto-update service definition |
+| `AutoUpdateServiceType` | `type` | Auto-update service method signatures |
+
+-> See [docs/built-in-services.md](./docs/built-in-services.md) for details.
+
+### Config Manager
+| API | Type | Description |
+|-----|------|-------------|
+| `getConfig` | `function` | Loads JSON config with file-watching and caching |
+
+-> See [docs/config-manager.md](./docs/config-manager.md) for details.
+
+### Legacy V1
+| API | Type | Description |
+|-----|------|-------------|
+| `handleV1Connection` | `function` | V1 legacy WebSocket handler (auto-update only) |
+
+-> See [docs/legacy-v1.md](./docs/legacy-v1.md) for details.
+
+### Main ServiceServer
+| API | Type | Description |
+|-----|------|-------------|
+| `ServiceServer` | `class` | Main server class (Fastify + WebSocket + auth) |
+| `createServiceServer` | `function` | Factory function to create a ServiceServer |
+
+-> See [docs/service-server.md](./docs/service-server.md) for details.
+
+## Usage Examples
 
 ### Basic Server Setup
 
-```ts
+```typescript
 import { createServiceServer, defineService, auth } from "@simplysm/service-server";
 
-// Define a service
 const GreetService = defineService("Greet", (ctx) => ({
   hello(name: string) {
-    return `Hello, ${name}!`;
+    return \`Hello, \${name}!\`;
   },
-  // Protected method requiring authentication
   secret: auth(["admin"], (msg: string) => {
-    return `Secret for ${ctx.authInfo}: ${msg}`;
+    return \`Secret for \${ctx.authInfo}: \${msg}\`;
   }),
 }));
 
-// Create and start the server
 const server = createServiceServer({
   rootPath: process.cwd(),
   port: 3000,
@@ -70,40 +140,35 @@ await server.listen();
 
 ### JWT Authentication
 
-```ts
+```typescript
 import { signJwt, verifyJwt } from "@simplysm/service-server";
 
-// Sign a token
 const token = await signJwt("my-secret", {
   roles: ["admin"],
   data: { userId: 1 },
 });
 
-// Verify a token
 const payload = await verifyJwt("my-secret", token);
 ```
 
 ### Event Broadcasting
 
-```ts
+```typescript
 import { defineEvent } from "@simplysm/service-common";
 
 const NotifyEvent = defineEvent<{ userId: number }, { text: string }>("Notify");
-
-// Emit from server
 await server.emitEvent(NotifyEvent, (info) => info.userId === 42, { text: "Hello!" });
 ```
 
-### ORM Service
+### Built-in ORM Service
 
-The server includes a built-in `OrmService` for database operations. Include it in your service list:
-
-```ts
+```typescript
 import { createServiceServer, OrmService } from "@simplysm/service-server";
 
 const server = createServiceServer({
   rootPath: process.cwd(),
   port: 3000,
+  auth: { jwtSecret: "my-secret" },
   services: [OrmService],
 });
 ```

package/docs/auth.md

@@ -1,13 +1,11 @@
-# Auth
+# Authentication (JWT)
 
-JWT authentication utilities for signing, verifying, and decoding tokens.
+## `AuthTokenPayload`
 
-## AuthTokenPayload\<TAuthInfo\>
+JWT token payload extending `JWTPayload` from `jose`. Contains roles and custom authentication data.
 
-JWT token payload extending the standard `JWTPayload` with role-based access and custom data.
-
-```ts
-interface AuthTokenPayload<TAuthInfo = unknown> extends JWTPayload {
+```typescript
+export interface AuthTokenPayload<TAuthInfo = unknown> extends JWTPayload {
   roles: string[];
   data: TAuthInfo;
 }
@@ -15,17 +13,16 @@ interface AuthTokenPayload<TAuthInfo = unknown> extends JWTPayload {
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `roles` | `string[]` | Role names for permission checking |
-| `data` | `TAuthInfo` | Custom authentication data (e.g., user info) |
-
-Inherits all standard JWT fields from `JWTPayload` (e.g., `iss`, `sub`, `aud`, `exp`, `nbf`, `iat`, `jti`).
+| `roles` | `string[]` | User roles for permission checking |
+| `data` | `TAuthInfo` | Custom authentication data (user info, etc.) |
+| *(inherited from JWTPayload)* | | Standard JWT claims (`iss`, `sub`, `aud`, `exp`, `nbf`, `iat`, `jti`) |
 
-## signJwt
+## `signJwt`
 
-Sign a JWT token with the given secret and payload.
+Signs a JWT token using HS256 algorithm with 12-hour expiration.
 
-```ts
-async function signJwt<TAuthInfo = unknown>(
+```typescript
+export async function signJwt<TAuthInfo = unknown>(
   jwtSecret: string,
   payload: AuthTokenPayload<TAuthInfo>,
 ): Promise<string>;
@@ -33,17 +30,17 @@ async function signJwt<TAuthInfo = unknown>(
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `jwtSecret` | `string` | Secret key for signing |
+| `jwtSecret` | `string` | JWT signing secret |
 | `payload` | `AuthTokenPayload<TAuthInfo>` | Token payload with roles and data |
 
-Returns the signed JWT string.
+**Returns:** `Promise<string>` -- Signed JWT token string.
 
-## verifyJwt
+## `verifyJwt`
 
-Verify a JWT token and return its payload. Throws if the token is invalid or expired.
+Verifies a JWT token and returns the decoded payload. Throws on expired or invalid tokens.
 
-```ts
-async function verifyJwt<TAuthInfo = unknown>(
+```typescript
+export async function verifyJwt<TAuthInfo = unknown>(
   jwtSecret: string,
   token: string,
 ): Promise<AuthTokenPayload<TAuthInfo>>;
@@ -51,21 +48,27 @@ async function verifyJwt<TAuthInfo = unknown>(
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `jwtSecret` | `string` | Secret key for verification |
-| `token` | `string` | JWT token string |
+| `jwtSecret` | `string` | JWT verification secret |
+| `token` | `string` | JWT token string to verify |
 
-Returns the decoded and verified `AuthTokenPayload`.
+**Returns:** `Promise<AuthTokenPayload<TAuthInfo>>` -- Decoded token payload.
 
-## decodeJwt
+**Throws:**
+- `Error("Token expired")` when the token has expired
+- `Error("Invalid token")` for any other verification failure
 
-Decode a JWT token without verification. Useful for inspecting token contents without validating the signature.
+## `decodeJwt`
 
-```ts
-function decodeJwt<TAuthInfo = unknown>(token: string): AuthTokenPayload<TAuthInfo>;
+Decodes a JWT token without verification. Useful for reading claims before verification.
+
+```typescript
+export function decodeJwt<TAuthInfo = unknown>(
+  token: string,
+): AuthTokenPayload<TAuthInfo>;
 ```
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `token` | `string` | JWT token string |
+| `token` | `string` | JWT token string to decode |
 
-Returns the decoded `AuthTokenPayload` (unverified).
+**Returns:** `AuthTokenPayload<TAuthInfo>` -- Decoded token payload (not verified).

package/docs/built-in-services.md

@@ -0,0 +1,61 @@
+# ORM/AutoUpdate Services
+
+## `OrmService`
+
+Built-in ORM service definition. Provides database connection, transaction management, and query execution over the WebSocket RPC layer. Requires authentication (wrapped with `auth()`).
+
+```typescript
+export const OrmService: ServiceDefinition;
+```
+
+The ORM service is registered with the name `"Orm"` and requires WebSocket transport (HTTP is not supported).
+
+Database connections are tracked per socket. When a WebSocket connection closes, all associated DB connections are automatically cleaned up.
+
+Methods (matching the `OrmService` interface from `@simplysm/service-common`):
+
+| Method | Parameters | Return | Description |
+|--------|-----------|--------|-------------|
+| `getInfo` | `opt: DbConnOptions & { configName: string }` | `Promise<{ dialect: Dialect; database?: string; schema?: string }>` | Gets database info from server config |
+| `connect` | `opt: DbConnOptions & { configName: string }` | `Promise<number>` | Opens a DB connection. Returns connection ID |
+| `close` | `connId: number` | `Promise<void>` | Closes a DB connection |
+| `beginTransaction` | `connId: number, isolationLevel?: IsolationLevel` | `Promise<void>` | Begins a transaction |
+| `commitTransaction` | `connId: number` | `Promise<void>` | Commits a transaction |
+| `rollbackTransaction` | `connId: number` | `Promise<void>` | Rolls back a transaction |
+| `executeParametrized` | `connId: number, query: string, params?: unknown[]` | `Promise<unknown[][]>` | Executes a parameterized query |
+| `executeDefs` | `connId: number, defs: QueryDef[], options?: (ResultMeta \| undefined)[]` | `Promise<unknown[][]>` | Executes query definitions with optional result parsing |
+| `bulkInsert` | `connId: number, tableName: string, columnDefs: Record<string, ColumnMeta>, records: Record<string, unknown>[]` | `Promise<void>` | Performs bulk insert |
+
+Configuration: Reads from the `"orm"` section of the server config file (`.config.json`).
+
+## `OrmServiceType`
+
+Type alias for the ORM service methods. Useful for client-side type sharing.
+
+```typescript
+export type OrmServiceType = ServiceMethods<typeof OrmService>;
+```
+
+## `AutoUpdateService`
+
+Built-in auto-update service definition. Provides version lookup for client applications. Does not require authentication.
+
+```typescript
+export const AutoUpdateService: ServiceDefinition;
+```
+
+Registered with the name `"AutoUpdate"`. Scans `{clientPath}/{platform}/updates/` for versioned files (`.exe` for desktop, `.apk` for Android).
+
+Methods:
+
+| Method | Parameters | Return | Description |
+|--------|-----------|--------|-------------|
+| `getLastVersion` | `platform: string` | `Promise<{ version: string; downloadPath: string } \| undefined>` | Returns the latest version info for the given platform. Uses `semver.maxSatisfying` to find the highest version |
+
+## `AutoUpdateServiceType`
+
+Type alias for the auto-update service methods.
+
+```typescript
+export type AutoUpdateServiceType = ServiceMethods<typeof AutoUpdateService>;
+```

package/docs/config-manager.md

@@ -0,0 +1,24 @@
+# Config Manager
+
+## `getConfig`
+
+Loads a JSON configuration file with automatic caching and file-watching for live reload.
+
+```typescript
+export async function getConfig<TConfig>(
+  filePath: string,
+): Promise<TConfig | undefined>;
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `filePath` | `string` | Absolute path to the JSON config file |
+
+**Returns:** `Promise<TConfig | undefined>` -- Parsed config object, or `undefined` if the file does not exist.
+
+Behavior:
+- **Caching:** Uses `LazyGcMap` with 10-minute GC interval and 1-hour expiry
+- **File watching:** Registers a file watcher on first load. Config is automatically reloaded when the file changes
+- **Expiry:** When a cache entry expires, the associated file watcher is cleaned up
+- **Deletion:** If the config file is deleted, the cache entry and watcher are removed
+- Used internally by `ServiceContext.getConfig()` to load root and client config files

package/docs/http-handlers.md

@@ -0,0 +1,83 @@
+# HTTP Handlers
+
+## `handleHttpRequest`
+
+Handles HTTP RPC requests. Supports both GET (with JSON query parameter) and POST (with JSON array body) methods.
+
+```typescript
+export async function handleHttpRequest<TAuthInfo = unknown>(
+  req: FastifyRequest,
+  reply: FastifyReply,
+  jwtSecret: string | undefined,
+  runMethod: (def: {
+    serviceName: string;
+    methodName: string;
+    params: unknown[];
+    http: { clientName: string; authTokenPayload?: AuthTokenPayload<TAuthInfo> };
+  }) => Promise<unknown>,
+): Promise<void>;
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `req` | `FastifyRequest` | Fastify request (expects `/:service/:method` route params) |
+| `reply` | `FastifyReply` | Fastify reply |
+| `jwtSecret` | `string \| undefined` | JWT secret for token verification |
+| `runMethod` | callback | Service method executor |
+
+Request requirements:
+- Header `x-sd-client-name` is required
+- GET: requires `?json=<encoded-params>` query parameter
+- POST: requires JSON array body
+- Authorization header (optional): `Bearer <token>`
+
+## `handleUpload`
+
+Handles multipart file uploads. Saves files to `{rootPath}/www/uploads/` with UUID-based filenames.
+
+```typescript
+export async function handleUpload(
+  req: FastifyRequest,
+  reply: FastifyReply,
+  rootPath: string,
+  jwtSecret: string | undefined,
+): Promise<void>;
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `req` | `FastifyRequest` | Fastify multipart request |
+| `reply` | `FastifyReply` | Fastify reply |
+| `rootPath` | `string` | Server root path |
+| `jwtSecret` | `string \| undefined` | JWT secret for authentication |
+
+Behavior:
+- Requires multipart request and valid Authorization header
+- Saves each file with a UUID filename preserving the original extension
+- Returns `ServiceUploadResult[]` on success
+- Cleans up all files on error (both partially written and already saved)
+
+## `handleStaticFile`
+
+Serves static files from `{rootPath}/www/` with security guards.
+
+```typescript
+export async function handleStaticFile(
+  req: FastifyRequest,
+  reply: FastifyReply,
+  rootPath: string,
+  urlPath: string,
+): Promise<void>;
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `req` | `FastifyRequest` | Fastify request |
+| `reply` | `FastifyReply` | Fastify reply |
+| `rootPath` | `string` | Server root path |
+| `urlPath` | `string` | Decoded URL path (without leading slash) |
+
+Security:
+- Path traversal attack prevention (rejects paths outside `{rootPath}/www/`)
+- Hidden file access denied (files starting with `.` return 403)
+- Directory requests redirect to add trailing slash, then serve `index.html`

package/docs/legacy-v1.md

@@ -0,0 +1,25 @@
+# Legacy V1
+
+## `handleV1Connection`
+
+Handles V1 legacy WebSocket connections. Only supports the `SdAutoUpdateService.getLastVersion` command. All other requests return an upgrade-required error.
+
+```typescript
+export function handleV1Connection(
+  socket: WebSocket,
+  autoUpdateMethods: { getLastVersion: (platform: string) => Promise<any> },
+  clientNameSetter?: (clientName: string | undefined) => void,
+): void;
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `socket` | `WebSocket` (from `ws`) | Raw WebSocket connection |
+| `autoUpdateMethods` | `{ getLastVersion: (platform: string) => Promise<any> }` | Auto-update method implementations |
+| `clientNameSetter` | `((clientName: string \| undefined) => void)?` | Callback to set the legacy client name on the context |
+
+V1 protocol:
+- Sends `{ name: "connected" }` on connection
+- Expects JSON messages with `{ uuid, command, params, clientName? }` format
+- Responds with `{ name: "response", reqUuid, state: "success"|"error", body }` format
+- Only `SdAutoUpdateService.getLastVersion` is supported; all other commands return `UPGRADE_REQUIRED` error

package/docs/protocol-wrapper.md

@@ -0,0 +1,37 @@
+# Protocol Wrapper
+
+## `ServerProtocolWrapper`
+
+Server-side protocol wrapper that automatically offloads heavy message encoding/decoding to a worker thread. Light operations are processed on the main thread.
+
+```typescript
+export interface ServerProtocolWrapper {
+  encode(uuid: string, message: ServiceMessage): Promise<{ chunks: Bytes[]; totalSize: number }>;
+  decode(bytes: Bytes): Promise<ServiceMessageDecodeResult<ServiceMessage>>;
+  dispose(): void;
+}
+```
+
+| Method | Parameters | Return | Description |
+|--------|-----------|--------|-------------|
+| `encode` | `uuid: string, message: ServiceMessage` | `Promise<{ chunks: Bytes[]; totalSize: number }>` | Encodes a message. Offloads to worker for messages with `Uint8Array` bodies |
+| `decode` | `bytes: Bytes` | `Promise<ServiceMessageDecodeResult<ServiceMessage>>` | Decodes binary data. Offloads to worker for payloads > 30KB |
+| `dispose` | none | `void` | Disposes the underlying protocol's GC timer |
+
+## `createServerProtocolWrapper`
+
+Creates a `ServerProtocolWrapper` instance.
+
+```typescript
+export function createServerProtocolWrapper(): ServerProtocolWrapper;
+```
+
+**Returns:** `ServerProtocolWrapper`
+
+Worker thread details:
+- Uses `@simplysm/core-node` `Worker` (Node.js `worker_threads`)
+- Shared singleton worker instance across all protocol wrappers
+- Worker memory limit: 4096 MB (old generation)
+- Size threshold for worker offloading: 30KB
+- Encode uses worker when body contains `Uint8Array` elements
+- Decode uses worker when total bytes exceed 30KB

package/docs/server-options.md

@@ -0,0 +1,31 @@
+# Server Options
+
+## `ServiceServerOptions`
+
+Server configuration options.
+
+```typescript
+export interface ServiceServerOptions {
+  rootPath: string;
+  port: number;
+  ssl?: {
+    pfxBytes: Uint8Array;
+    passphrase: string;
+  };
+  auth?: {
+    jwtSecret: string;
+  } | false;
+  services: ServiceDefinition[];
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `rootPath` | `string` | Root directory path. Static files are served from `{rootPath}/www/`, config loaded from `{rootPath}/.config.json` |
+| `port` | `number` | Server listen port |
+| `ssl` | `{ pfxBytes: Uint8Array; passphrase: string }?` | SSL/TLS configuration using PFX certificate |
+| `ssl.pfxBytes` | `Uint8Array` | PFX certificate file contents |
+| `ssl.passphrase` | `string` | PFX certificate passphrase |
+| `auth` | `{ jwtSecret: string } \| false` | Authentication configuration. `undefined` = auto-detect (error if auth-wrapped services exist). `false` = explicitly disable auth checks. `{ jwtSecret }` = enable JWT auth |
+| `auth.jwtSecret` | `string` | JWT signing/verification secret (HS256) |
+| `services` | `ServiceDefinition[]` | Array of service definitions to register |