@opsimathically/nodenetproccalld 0.0.1

package/LICENSE.txt

@@ -0,0 +1 @@
+Set your license text here.

package/README.md

@@ -0,0 +1,199 @@
+# nodenetproccalld
+
+`nodenetproccalld` is a standalone TypeScript daemon that wraps:
+
+- `@opsimathically/workerprocedurecall`
+- `@opsimathically/networkprocedurecall`
+
+It exposes a resilient mTLS TCP service with API-key authentication and privilege-based access control for remote function operations (`invoke`, `define`, `undefine`, constants, dependencies).
+
+## Features
+
+- mTLS TCP daemon (`tls.createServer`) via `NetworkProcedureCall`
+- API key auth callback with privilege mapping and optional TLS identity constraints
+- JSON5 config files with comments/trailing commas support
+- Startup validation for config shape, regex rules, and TLS PEM file presence
+- Worker pool startup and worker event logging
+- Graceful shutdown on `SIGINT` / `SIGTERM` / uncaught process errors
+- Optional periodic runtime metrics logging
+
+## Config Files
+
+Default paths:
+
+- `./config/server.config.json5`
+- `./config/api_keys.config.json5`
+
+Sample files are included in `config/`.
+
+### Server Config (`server.config.json5`)
+
+Defines:
+
+- `information.server_name`
+- `network.bind_addr` and `network.tcp_listen_port`
+- `tls_mtls` file paths and TLS options
+- `workerprocedurecall` worker count/options
+- optional `abuse_controls`
+- optional `observability` options
+
+`tls_mtls.key_file`, `cert_file`, and `ca_file` are required and resolved relative to the server config file directory when not absolute paths.
+
+### API Keys Config (`api_keys.config.json5`)
+
+Defines:
+
+- `api_keys[]` entries with:
+- `key_id`
+- `api_key`
+- `privileges`
+- optional `enabled`
+- optional `identity_constraints` regex patterns (`remote_address`, peer cert fields)
+
+## Running
+
+1. Build:
+
+```bash
+npm run build
+```
+
+2. Start daemon with default config paths:
+
+```bash
+npm run start
+```
+
+3. Generate TLS material for fresh installs (CA/server/client):
+
+```bash
+node dist/index.js --generate-tls-material
+```
+
+By default this writes:
+
+- `./config/certs/ca.key.pem`
+- `./config/certs/ca.cert.pem`
+- `./config/certs/server.key.pem`
+- `./config/certs/server.cert.pem`
+- `./config/certs/client.key.pem`
+- `./config/certs/client.cert.pem`
+
+Useful options:
+
+```bash
+node dist/index.js \
+  --generate-tls-material \
+  --tls-output-dir ./config/certs \
+  --tls-overwrite \
+  --tls-ca-cn my-local-ca \
+  --tls-server-cn localhost \
+  --tls-client-cn daemon-client \
+  --tls-valid-days 365
+```
+
+4. Start daemon with custom config paths:
+
+```bash
+node dist/index.js \
+  --server-config /absolute/or/relative/server.config.json5 \
+  --api-keys-config /absolute/or/relative/api_keys.config.json5
+```
+
+5. CLI help:
+
+```bash
+node dist/index.js --help
+```
+
+Installed package binaries:
+
+- `nodenetproccalld`
+
+## Packaging and Deployment
+
+TypeScript daemons are usually deployed as built JavaScript plus a Node.js runtime.
+
+### Local package artifact
+
+Build and create a deployable tarball:
+
+```bash
+npm run build
+npm pack
+```
+
+This creates a file like:
+
+- `opsimathically-nodenetproccalld-0.0.1.tgz`
+
+### Install on target host
+
+Install Node.js LTS on target host, then install daemon package globally:
+
+```bash
+npm install -g ./opsimathically-nodenetproccalld-0.0.1.tgz
+```
+
+Then run:
+
+```bash
+nodenetproccalld --help
+```
+
+### Typical service deployment (systemd)
+
+Example `/etc/systemd/system/nodenetproccalld.service`:
+
+```ini
+[Unit]
+Description=nodenetproccalld
+After=network.target
+
+[Service]
+Type=simple
+User=nodenetprocd
+WorkingDirectory=/opt/nodenetproccalld
+ExecStart=/usr/bin/nodenetproccalld --server-config /opt/nodenetproccalld/config/server.config.json5 --api-keys-config /opt/nodenetproccalld/config/api_keys.config.json5
+Restart=always
+RestartSec=2
+Environment=NODE_ENV=production
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Then:
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl enable nodenetproccalld
+sudo systemctl start nodenetproccalld
+sudo systemctl status nodenetproccalld
+```
+
+## Development
+
+- Run tests:
+
+```bash
+npm test
+```
+
+- Run type checking:
+
+```bash
+npm run typecheck
+```
+
+- Run daemon directly from TypeScript sources:
+
+```bash
+npm run start:daemon -- --server-config ./config/server.config.json5 --api-keys-config ./config/api_keys.config.json5
+```
+
+## mTLS Notes
+
+- Use a private CA for server and client certs.
+- Ensure client `servername` matches server cert SAN/CN (for local examples, `localhost`).
+- Keep API key privileges minimal (`all_privileges` only for trusted operators).

package/config/api_keys.config.json5

@@ -0,0 +1,21 @@
+{
+  // API keys and privilege grants for auth_callback.
+  api_keys: [
+    {
+      key_id: 'admin_key_1',
+      api_key: 'replace_me_with_random_secret',
+      privileges: ['all_privileges'],
+      enabled: true,
+      identity_constraints: {
+        // Example: accept loopback clients only.
+        remote_address_regex: '^(127\\.0\\.0\\.1|::1|::ffff:127\\.0\\.0\\.1)$'
+      }
+    },
+    {
+      key_id: 'invoke_only_key_1',
+      api_key: 'replace_me_with_second_secret',
+      privileges: ['invoke_functions'],
+      enabled: false
+    }
+  ]
+}

package/config/server.config.json5

@@ -0,0 +1,79 @@
+{
+  // Friendly name that clients can use in their own config maps.
+  information: {
+    server_name: 'daemon_server_1'
+  },
+
+  // Bind target for tls.createServer.
+  network: {
+    bind_addr: '0.0.0.0',
+    tcp_listen_port: 6767
+  },
+
+  // PEM files are resolved relative to this config file unless absolute paths are used.
+  tls_mtls: {
+    key_file: './certs/server.key.pem',
+    cert_file: './certs/server.cert.pem',
+    ca_file: './certs/ca.cert.pem',
+    // crl_file: './certs/ca.crl.pem',
+    min_version: 'TLSv1.3',
+    handshake_timeout_ms: 5000,
+    request_timeout_ms: 15000,
+    max_frame_bytes: 1048576
+  },
+
+  workerprocedurecall: {
+    count: 4,
+    constructor_options: {
+      call_timeout_ms: 30000,
+      control_timeout_ms: 10000,
+      restart_on_failure: true,
+      max_restarts_per_worker: 6,
+      max_pending_calls_per_worker: 500
+    },
+    start_options: {
+      restart_base_delay_ms: 150,
+      restart_max_delay_ms: 5000,
+      restart_jitter_ms: 250
+    }
+  },
+
+  // Optional abuse controls from @opsimathically/networkprocedurecall.
+  abuse_controls: {
+    connection_controls: {
+      max_concurrent_sockets: 1024,
+      max_concurrent_handshakes: 256,
+      max_unauthenticated_sessions: 256,
+      per_ip_max_new_connections_per_window: 64,
+      tls_handshake_timeout_ms: 5000,
+      auth_message_timeout_ms: 5000
+    },
+    request_controls: {
+      max_in_flight_requests_per_connection: 128,
+      per_connection: {
+        enabled: true,
+        tokens_per_interval: 200,
+        interval_ms: 1000,
+        burst_tokens: 400
+      },
+      per_api_key: {
+        enabled: true,
+        tokens_per_interval: 1000,
+        interval_ms: 1000,
+        burst_tokens: 2000
+      },
+      per_ip: {
+        enabled: true,
+        tokens_per_interval: 500,
+        interval_ms: 1000,
+        burst_tokens: 1000
+      }
+    }
+  },
+
+  observability: {
+    enable_console_log: true,
+    log_worker_events: true,
+    metrics_log_interval_ms: 30000
+  }
+}

package/dist/index.d.mts

@@ -0,0 +1,246 @@
+import { privilege_name_t, networkprocedurecall_auth_callback_t, tls_min_version_t, networkprocedurecall_abuse_controls_t, networkprocedurecall_auth_success_t, networkprocedurecall_abuse_metrics_t } from '@opsimathically/networkprocedurecall';
+import { workerprocedurecall_constructor_params_t, start_workers_params_t } from '@opsimathically/workerprocedurecall';
+
+type daemon_tls_file_config_t = {
+  key_file: string;
+  cert_file: string;
+  ca_file: string;
+  crl_file?: string;
+  min_version?: tls_min_version_t;
+  cipher_suites?: string;
+  handshake_timeout_ms?: number;
+  request_timeout_ms?: number;
+  max_frame_bytes?: number;
+};
+
+type daemon_worker_config_t = {
+  count: number;
+  constructor_options?: workerprocedurecall_constructor_params_t;
+  start_options?: Omit<start_workers_params_t, 'count'>;
+};
+
+type daemon_observability_config_t = {
+  enable_console_log?: boolean;
+  log_worker_events?: boolean;
+  metrics_log_interval_ms?: number;
+};
+
+type daemon_server_config_file_t = {
+  information: {
+    server_name: string;
+  };
+  network: {
+    bind_addr: string;
+    tcp_listen_port: number;
+  };
+  tls_mtls: daemon_tls_file_config_t;
+  workerprocedurecall: daemon_worker_config_t;
+  abuse_controls?: networkprocedurecall_abuse_controls_t;
+  observability?: daemon_observability_config_t;
+};
+
+type daemon_api_key_identity_constraints_t = {
+  remote_address_regex?: string;
+  tls_peer_subject_regex?: string;
+  tls_peer_san_regex?: string;
+  tls_peer_fingerprint256_regex?: string;
+  tls_peer_serial_number_regex?: string;
+};
+
+type daemon_api_key_entry_t = {
+  key_id: string;
+  api_key: string;
+  privileges: privilege_name_t[];
+  enabled?: boolean;
+  identity_constraints?: daemon_api_key_identity_constraints_t;
+};
+
+type daemon_api_keys_config_file_t = {
+  api_keys: daemon_api_key_entry_t[];
+};
+
+type daemon_compiled_identity_constraints_t = {
+  remote_address_regex?: RegExp;
+  tls_peer_subject_regex?: RegExp;
+  tls_peer_san_regex?: RegExp;
+  tls_peer_fingerprint256_regex?: RegExp;
+  tls_peer_serial_number_regex?: RegExp;
+};
+
+type daemon_runtime_api_key_entry_t = Omit<
+  daemon_api_key_entry_t,
+  'identity_constraints' | 'enabled'
+> & {
+  enabled: boolean;
+  identity_constraints?: daemon_compiled_identity_constraints_t;
+};
+
+type daemon_resolved_tls_mtls_t = {
+  key_pem: string;
+  cert_pem: string;
+  ca_pem: string;
+  crl_pem?: string;
+  min_version?: tls_min_version_t;
+  cipher_suites?: string;
+  handshake_timeout_ms?: number;
+  request_timeout_ms?: number;
+  max_frame_bytes?: number;
+};
+
+type daemon_runtime_config_t = {
+  server_config: Omit<daemon_server_config_file_t, 'tls_mtls'> & {
+    tls_mtls: daemon_resolved_tls_mtls_t;
+  };
+  api_keys_config: {
+    api_keys: daemon_runtime_api_key_entry_t[];
+  };
+};
+
+type daemon_config_paths_t = {
+  server_config_path: string;
+  api_keys_config_path: string;
+};
+
+type daemon_tls_generation_options_t = {
+  enabled: boolean;
+  output_dir: string;
+  overwrite: boolean;
+  ca_common_name: string;
+  server_common_name: string;
+  client_common_name: string;
+  valid_days: number;
+};
+
+type daemon_generated_tls_material_t = {
+  output_dir: string;
+  ca_key_path: string;
+  ca_cert_path: string;
+  server_key_path: string;
+  server_cert_path: string;
+  client_key_path: string;
+  client_cert_path: string;
+};
+
+type daemon_cli_options_t = daemon_config_paths_t & {
+  help: boolean;
+  tls_generation: daemon_tls_generation_options_t;
+};
+
+type daemon_auth_callback_params_t = Parameters<networkprocedurecall_auth_callback_t>[0];
+
+declare class ApiKeyAuthorizer {
+    private readonly api_key_entries;
+    constructor(params: {
+        api_key_entries: daemon_runtime_api_key_entry_t[];
+    });
+    authenticate(params: {
+        auth_callback_params: daemon_auth_callback_params_t;
+    }): Promise<'failed' | networkprocedurecall_auth_success_t>;
+    private matchesIdentityConstraints;
+    private matchOptionalValue;
+}
+
+declare class ConfigValidator {
+    validateServerConfig(params: {
+        server_config_raw: unknown;
+    }): daemon_server_config_file_t;
+    validateApiKeysConfig(params: {
+        api_keys_config_raw: unknown;
+    }): daemon_api_keys_config_file_t;
+    toRuntimeApiKeysConfig(params: {
+        api_keys_config: daemon_api_keys_config_file_t;
+    }): daemon_runtime_api_key_entry_t[];
+    private compileIdentityConstraints;
+    private assertUniqueApiKeys;
+    private assertUniqueKeyIds;
+}
+
+declare class ConfigFileLoader {
+    private readonly config_validator;
+    constructor(params?: {
+        config_validator?: ConfigValidator;
+    });
+    loadDaemonConfig(params: {
+        config_paths: daemon_config_paths_t;
+    }): daemon_runtime_config_t;
+    private readJson5File;
+    private resolveTlsMaterial;
+    private readPemFile;
+}
+
+declare class DaemonCli {
+    parseOptions(): daemon_cli_options_t;
+    printHelp(): void;
+}
+
+declare class DaemonProcess {
+    private readonly daemon;
+    private is_running;
+    private stop_in_progress;
+    private stop_resolve;
+    private readonly stop_waiter;
+    constructor(params: {
+        config_paths: daemon_config_paths_t;
+    });
+    run(): Promise<void>;
+    private attachProcessHandlers;
+    private detachProcessHandlers;
+    private readonly handleSignal;
+    private readonly handleUncaughtException;
+    private readonly handleUnhandledRejection;
+    private requestStop;
+}
+
+type daemon_lifecycle_state_t = 'stopped' | 'starting' | 'running' | 'stopping';
+type daemon_runtime_snapshot_t = {
+    lifecycle_state: daemon_lifecycle_state_t;
+    server_name?: string;
+    bind_addr?: string;
+    tcp_listen_port?: number;
+    worker_health_states?: unknown;
+    abuse_metrics?: networkprocedurecall_abuse_metrics_t;
+};
+declare class NetworkProcedureCallDaemon {
+    private readonly config_paths;
+    private readonly config_file_loader;
+    private lifecycle_state;
+    private daemon_config;
+    private workerprocedurecall;
+    private networkprocedurecall;
+    private api_key_authorizer;
+    private worker_event_listener_id;
+    private metrics_log_interval_handle;
+    constructor(params: {
+        config_paths: daemon_config_paths_t;
+        config_file_loader?: ConfigFileLoader;
+    });
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    getRuntimeSnapshot(): daemon_runtime_snapshot_t;
+    private createAuthCallback;
+    private buildServerStartParams;
+    private startMetricsLogging;
+    private clearMetricsLoggingInterval;
+    private stopBestEffort;
+    private requireDaemonConfig;
+    private requireApiKeyAuthorizer;
+    private logWorkerEvent;
+    private logMessage;
+}
+
+declare class TlsMaterialGenerator {
+    generateTlsMaterial(params: {
+        tls_generation_options: daemon_tls_generation_options_t;
+    }): daemon_generated_tls_material_t;
+    private assertOpenSslAvailable;
+    private buildTlsFileMap;
+    private assertTargetFilesAreWritable;
+    private generateCa;
+    private generateServerCertificate;
+    private generateClientCertificate;
+    private cleanupIntermediateFiles;
+    private runOpenSslCommand;
+    private getErrorMessage;
+}
+
+export { ApiKeyAuthorizer, ConfigFileLoader, ConfigValidator, DaemonCli, DaemonProcess, NetworkProcedureCallDaemon, TlsMaterialGenerator, type daemon_api_key_entry_t, type daemon_api_key_identity_constraints_t, type daemon_api_keys_config_file_t, type daemon_cli_options_t, type daemon_config_paths_t, type daemon_generated_tls_material_t, type daemon_observability_config_t, type daemon_runtime_api_key_entry_t, type daemon_runtime_config_t, type daemon_server_config_file_t, type daemon_tls_file_config_t, type daemon_tls_generation_options_t, type daemon_worker_config_t };