bunqueue 2.8.7 → 2.8.8

package/dist/cli/client.d.ts

@@ -2,6 +2,7 @@
  * CLI TCP Client
  * Connects to bunQ server and executes commands (msgpack binary protocol)
  */
+import type { ClientTlsOptions } from '../client/tcp/types';
 /** Client options */
 export interface ClientOptions {
     /** Server host */
@@ -10,6 +11,8 @@ export interface ClientOptions {
     port: number;
     /** Auth token */
     token?: string;
+    /** TLS to the server (true = system CAs, object = custom CA / no-verify) */
+    tls?: boolean | ClientTlsOptions;
     /** Output as JSON */
     json: boolean;
 }

package/dist/cli/client.js

@@ -6,6 +6,7 @@ import { formatOutput, formatError } from './output';
 import { pack, unpack } from 'msgpackr';
 import { FrameParser, FrameSizeError } from '../infrastructure/server/protocol';
 import { CommandError } from './commands/types';
+import { buildClientTls } from '../client/tcp/connection';
 /** Send a command and wait for response */
 async function sendCommand(socket, command) {
     return new Promise((resolve, reject) => {
@@ -45,7 +46,10 @@ async function connect(options) {
                 catch (err) {
                     if (err instanceof FrameSizeError) {
                         if (socketData.reject) {
-                            socketData.reject(new Error(`Frame too large: ${err.requestedSize} bytes exceeds maximum ${err.maxSize}`));
+                            // A plaintext client reading a TLS handshake sees garbage that
+                            // parses as an absurd frame size — hint at the likely cause.
+                            socketData.reject(new Error(`Frame too large: ${err.requestedSize} bytes exceeds maximum ${err.maxSize}` +
+                                ' (is the server running with TLS? try --tls, --tls-ca or --tls-no-verify)'));
                             socketData.resolve = null;
                             socketData.reject = null;
                         }
@@ -95,11 +99,18 @@ async function connect(options) {
                 reject(new Error(`Failed to connect to ${targetDesc}: ${error.message}`));
             },
         };
-        // Connect via TCP
+        // Connect via TCP (optionally wrapped in TLS)
+        const tlsValue = buildClientTls(options.tls);
         void Bun.connect({
             hostname: options.host,
             port: options.port,
+            ...(tlsValue !== undefined && { tls: tlsValue }),
             socket: socketHandlers,
+        }).catch((err) => {
+            // Bun.connect can reject directly (e.g. TLS handshake refused) instead of
+            // firing connectError — surface it instead of waiting out the timeout.
+            const message = err instanceof Error ? err.message : String(err);
+            reject(new Error(`Failed to connect to ${targetDesc}: ${message}`));
         });
         // Handle connection timeout
         const connectionTimeoutId = setTimeout(() => {

package/dist/cli/commands/server.js

@@ -5,7 +5,7 @@
 import { parseArgs } from 'node:util';
 import { printServerHelp } from '../help';
 import { VERSION } from '../../shared/version';
-import { loadConfigFile, resolveServerConfig, resolveCloudConfig } from '../../config';
+import { loadConfigFile, resolveServerConfig, resolveCloudConfig, resolveTlsServerOptions, } from '../../config';
 /** Validate port number */
 function validatePort(value, name, defaultPort) {
     const port = parseInt(value, 10);
@@ -25,6 +25,8 @@ function parseCliFlags(args) {
             host: { type: 'string' },
             'data-path': { type: 'string' },
             'auth-tokens': { type: 'string' },
+            'tls-cert': { type: 'string' },
+            'tls-key': { type: 'string' },
             config: { type: 'string', short: 'c' },
         },
         allowPositionals: false,
@@ -46,6 +48,12 @@ function parseCliFlags(args) {
     if (values['auth-tokens']) {
         flags.authTokens = values['auth-tokens'].split(',').filter(Boolean);
     }
+    if (values['tls-cert']) {
+        flags.tlsCertFile = values['tls-cert'];
+    }
+    if (values['tls-key']) {
+        flags.tlsKeyFile = values['tls-key'];
+    }
     if (values.config) {
         flags.configPath = values.config;
     }
@@ -58,7 +66,9 @@ function applyCliFlags(fileConfig, flags) {
         flags.httpPort !== undefined ||
         flags.host !== undefined ||
         flags.dataPath !== undefined ||
-        flags.authTokens !== undefined;
+        flags.authTokens !== undefined ||
+        flags.tlsCertFile !== undefined ||
+        flags.tlsKeyFile !== undefined;
     if (!hasFlags && !fileConfig)
         return null;
     const base = fileConfig ?? {};
@@ -69,6 +79,8 @@ function applyCliFlags(fileConfig, flags) {
             ...(flags.tcpPort !== undefined && { tcpPort: flags.tcpPort }),
             ...(flags.httpPort !== undefined && { httpPort: flags.httpPort }),
             ...(flags.host !== undefined && { host: flags.host }),
+            ...(flags.tlsCertFile !== undefined && { tlsCertFile: flags.tlsCertFile }),
+            ...(flags.tlsKeyFile !== undefined && { tlsKeyFile: flags.tlsKeyFile }),
         },
         storage: {
             ...base.storage,
@@ -92,6 +104,15 @@ export async function runServer(args, showHelp) {
     const mergedConfig = applyCliFlags(fileConfig, flags);
     const config = resolveServerConfig(mergedConfig);
     const cloudConfig = resolveCloudConfig(mergedConfig, config.dataPath);
+    // Resolve TLS — fail fast on partial cert/key before binding anything
+    let tlsConfig;
+    try {
+        tlsConfig = resolveTlsServerOptions(config);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
     // Import and start the server components
     const { QueueManager } = await import('../../application/queueManager');
     const { createTcpServer } = await import('../../infrastructure/server/tcp');
@@ -110,11 +131,13 @@ export async function runServer(args, showHelp) {
             port: config.tcpPort,
             hostname: config.hostname,
             authTokens,
+            ...(tlsConfig && { tls: tlsConfig }),
         });
         httpServer = createHttpServer(qm, {
             port: config.httpPort,
             hostname: config.hostname,
             authTokens,
+            ...(tlsConfig && { tls: tlsConfig }),
         });
     }
     catch (err) {
@@ -159,6 +182,7 @@ ${dim}────────────────────────
   ${green}●${reset} TCP    ${tcpDisplay}
   ${green}●${reset} HTTP   ${httpDisplay}
   ${yellow}●${reset} Data   ${config.dataPath ?? 'in-memory'}
+  ${yellow}●${reset} TLS    ${tlsConfig ? `${green}enabled${reset}` : `${dim}disabled${reset}`}
   ${yellow}●${reset} Auth   ${authTokens ? `${green}enabled${reset}` : `${dim}disabled${reset}`}
   ${yellow}●${reset} Cloud  ${cloudConfig ? `${green}enabled${reset} ${dim}→ ${cloudConfig.url}${reset}` : `${dim}disabled${reset}`}
 

package/dist/cli/help.js

@@ -98,6 +98,9 @@ GLOBAL OPTIONS:
   -H, --host <host>               Server host (default: localhost)
   -p, --port <port>               TCP port (default: 6789)
   -t, --token <token>             Authentication token (env: BQ_TOKEN, BUNQUEUE_TOKEN)
+  --tls                           Connect with TLS (verify with system CAs)
+  --tls-ca <file>                 Trust a custom CA cert (implies --tls)
+  --tls-no-verify                 TLS without cert verification (self-signed, dev only)
   --json                          Output as JSON
   --help                          Show help
   --version                       Show version
@@ -125,6 +128,8 @@ Options:
   --host <host>           Bind address (default: 0.0.0.0, env: HOST)
   --data-path <path>      SQLite database path (env: DATA_PATH)
   --auth-tokens <list>    Comma-separated auth tokens (env: AUTH_TOKENS)
+  --tls-cert <file>       PEM certificate for native TLS (env: TLS_CERT_FILE)
+  --tls-key <file>        PEM private key for native TLS (env: TLS_KEY_FILE)
   --help                  Show this help
 
 Examples:

package/dist/cli/index.d.ts

@@ -8,6 +8,11 @@ interface GlobalOptions {
     host: string;
     port: number;
     token?: string;
+    /** TLS to the server: true = verify with system CAs, object = custom CA / no-verify */
+    tls?: boolean | {
+        rejectUnauthorized?: boolean;
+        caFile?: string;
+    };
     json: boolean;
     help: boolean;
     version: boolean;

package/dist/cli/index.js

@@ -35,6 +35,53 @@ function resolveEnvPort(currentPort) {
 function resolveEnvHost(currentHost) {
     return Bun.env.HOST ?? Bun.env.BUNQUEUE_HOST ?? Bun.env.BQ_HOST ?? currentHost;
 }
+/**
+ * Handle a `--tls*` global client flag and return the index to continue
+ * scanning from. Flags that are NOT client TLS flags (e.g. the server's
+ * --tls-cert/--tls-key) are passed through to `commandArgs`.
+ */
+function applyTlsFlag(arg, allArgs, i, state, commandArgs) {
+    if (arg === '--tls') {
+        state.enabled = true;
+        return i;
+    }
+    if (arg === '--tls-no-verify') {
+        state.noVerify = true;
+        return i;
+    }
+    if (arg === '--tls-ca') {
+        const nextArg = allArgs[i + 1];
+        // A following flag is not a path: don't swallow it (--tls-ca --json ...)
+        if (nextArg === undefined || nextArg.startsWith('-')) {
+            console.warn('Warning: --tls-ca requires a file path. Option ignored.');
+            return i;
+        }
+        state.caFile = nextArg;
+        return i + 1;
+    }
+    if (arg.startsWith('--tls-ca=')) {
+        const val = arg.slice(9);
+        if (!val) {
+            console.warn('Warning: --tls-ca= requires a file path. Option ignored.');
+        }
+        else {
+            state.caFile = val;
+        }
+        return i;
+    }
+    commandArgs.push(arg); // --tls-cert / --tls-key etc. → server flags, pass through
+    return i;
+}
+/** Build the GlobalOptions.tls value: --tls-ca / --tls-no-verify imply TLS */
+function buildTlsOption(state) {
+    if (state.noVerify || state.caFile !== undefined) {
+        return {
+            ...(state.noVerify && { rejectUnauthorized: false }),
+            ...(state.caFile !== undefined && { caFile: state.caFile }),
+        };
+    }
+    return state.enabled ? true : undefined;
+}
 /** Parse global options from process.argv */
 export function parseGlobalOptions() {
     const allArgs = process.argv.slice(2);
@@ -47,6 +94,7 @@ export function parseGlobalOptions() {
     let version = false;
     let hostExplicit = false;
     let portExplicit = false;
+    const tlsState = { enabled: false, noVerify: false };
     const commandArgs = [];
     let i = 0;
     while (i < allArgs.length) {
@@ -76,6 +124,9 @@ export function parseGlobalOptions() {
                 token = allArgs[++i];
             }
         }
+        else if (arg.startsWith('--tls')) {
+            i = applyTlsFlag(arg, allArgs, i, tlsState, commandArgs);
+        }
         else if (arg === '--json') {
             json = true;
         }
@@ -137,7 +188,7 @@ export function parseGlobalOptions() {
     if (!hostExplicit)
         host = resolveEnvHost(host);
     return {
-        options: { host, port, token, json, help, version },
+        options: { host, port, token, tls: buildTlsOption(tlsState), json, help, version },
         commandArgs,
     };
 }
@@ -231,6 +282,7 @@ export async function main() {
             host: options.host,
             port: options.port,
             token: options.token,
+            tls: options.tls,
             json: options.json,
         });
     }

package/dist/client/queue/queue.js

@@ -60,6 +60,7 @@ export class Queue {
                 this.tcpPool = getSharedPool({
                     host: connOpts.host,
                     port: connOpts.port,
+                    tls: connOpts.tls,
                     poolSize,
                     pingInterval: connOpts.pingInterval,
                     commandTimeout: connOpts.commandTimeout,
@@ -74,6 +75,7 @@ export class Queue {
                     host: connOpts.host ?? 'localhost',
                     port: connOpts.port ?? 6789,
                     token,
+                    tls: connOpts.tls,
                     poolSize,
                     pingInterval: connOpts.pingInterval,
                     commandTimeout: connOpts.commandTimeout,

package/dist/client/tcp/client.js

@@ -137,6 +137,7 @@ export class TcpClient extends EventEmitter {
         const { socket } = await createConnection({
             host: this.options.host,
             port: this.options.port,
+            tls: this.options.tls,
         }, this.options.connectTimeout, {
             onData: (frame) => {
                 this.handleData(frame);

package/dist/client/tcp/connection.d.ts

@@ -2,7 +2,7 @@
  * TCP Connection Handler
  * Manages low-level socket connection and data handling (msgpack binary protocol)
  */
-import type { SocketWrapper, PendingCommand } from './types';
+import type { SocketWrapper, PendingCommand, ClientTlsOptions } from './types';
 /** Connection events */
 export interface ConnectionEvents {
     onData: (frame: Uint8Array) => void;
@@ -20,7 +20,14 @@ export interface ConnectionTarget {
     host?: string;
     /** TCP port */
     port?: number;
+    /** Enable TLS: true (system CAs) or per-connection TLS options */
+    tls?: boolean | ClientTlsOptions;
 }
+/**
+ * Map client TLS options to the `tls` value accepted by Bun.connect.
+ * Returns undefined when TLS is disabled (plaintext, the default).
+ */
+export declare function buildClientTls(tls: boolean | ClientTlsOptions | undefined): true | Record<string, unknown> | undefined;
 /**
  * Establish TCP connection to server
  */

package/dist/client/tcp/connection.js

@@ -3,6 +3,20 @@
  * Manages low-level socket connection and data handling (msgpack binary protocol)
  */
 import { FrameParser, FrameSizeError } from '../../infrastructure/server/protocol';
+/**
+ * Map client TLS options to the `tls` value accepted by Bun.connect.
+ * Returns undefined when TLS is disabled (plaintext, the default).
+ */
+export function buildClientTls(tls) {
+    if (!tls)
+        return undefined;
+    if (tls === true)
+        return true;
+    return {
+        ...(tls.rejectUnauthorized !== undefined && { rejectUnauthorized: tls.rejectUnauthorized }),
+        ...(tls.caFile !== undefined && { ca: Bun.file(tls.caFile) }),
+    };
+}
 /**
  * Establish TCP connection to server
  */
@@ -82,11 +96,23 @@ export async function createConnection(target, connectTimeout, events) {
                 }
             },
         };
-        // Connect via TCP
+        // Connect via TCP (optionally wrapped in TLS — protocol is unchanged)
+        const tlsValue = buildClientTls(target.tls);
         void Bun.connect({
             hostname: target.host ?? 'localhost',
             port: target.port ?? 6789,
+            ...(tlsValue !== undefined && { tls: tlsValue }),
             socket: socketHandlers,
+        }).catch((error) => {
+            // Bun.connect rejects (instead of firing connectError) for some failure
+            // modes, e.g. a TLS handshake refused synchronously. Route it through the
+            // same rejection path so callers never hang until the connect timeout.
+            if (!connectionResolved) {
+                connectionResolved = true;
+                cleanup();
+                const message = error instanceof Error ? error.message : String(error);
+                reject(new Error(`Failed to connect to ${targetDesc}: ${message}`));
+            }
         });
         timeoutId = setTimeout(() => {
             if (!connectionResolved) {

package/dist/client/tcp/index.d.ts

@@ -2,7 +2,7 @@
  * TCP Client Module
  * Re-exports all TCP client components
  */
-export type { ConnectionOptions, ConnectionHealth, PendingCommand, SocketWrapper } from './types';
+export type { ConnectionOptions, ConnectionHealth, PendingCommand, SocketWrapper, ClientTlsOptions, } from './types';
 export { DEFAULT_CONNECTION } from './types';
 export { HealthTracker, type HealthConfig } from './health';
 export { ReconnectManager, type ReconnectConfig } from './reconnect';

package/dist/client/tcp/shared.d.ts

@@ -1,10 +1,12 @@
 /**
- * Shared TCP Client Instance
- * Singleton pattern for shared client management
+ * Shared TCP Client Instances
+ * One shared client per distinct connection target. Keyed by
+ * host/port/token/tls so callers with different configs (notably TLS vs
+ * plaintext to the same server) never receive each other's connection.
  */
 import type { ConnectionOptions } from './types';
 import { TcpClient } from './client';
-/** Get shared TCP client */
+/** Get shared TCP client for the given connection target */
 export declare function getSharedTcpClient(options?: Partial<ConnectionOptions>): TcpClient;
-/** Close shared client */
+/** Close all shared clients */
 export declare function closeSharedTcpClient(): void;

package/dist/client/tcp/shared.js

@@ -1,19 +1,35 @@
 /**
- * Shared TCP Client Instance
- * Singleton pattern for shared client management
+ * Shared TCP Client Instances
+ * One shared client per distinct connection target. Keyed by
+ * host/port/token/tls so callers with different configs (notably TLS vs
+ * plaintext to the same server) never receive each other's connection.
  */
 import { TcpClient } from './client';
-/** Shared client instance */
-let sharedClient = null;
-/** Get shared TCP client */
+/** Shared clients keyed by connection target */
+const sharedClients = new Map();
+/** Build the sharing key from the connection-identity options */
+function getClientKey(options) {
+    const host = options?.host ?? 'localhost';
+    const port = options?.port ?? 6789;
+    const token = options?.token ?? '';
+    const tokenHash = token ? String(Number(Bun.hash(token)) & 0xffff) : '0';
+    const tlsKey = options?.tls ? JSON.stringify(options.tls) : '0';
+    return `${host}:${port}:${tokenHash}:${tlsKey}`;
+}
+/** Get shared TCP client for the given connection target */
 export function getSharedTcpClient(options) {
-    sharedClient ??= new TcpClient(options);
-    return sharedClient;
+    const key = getClientKey(options);
+    let client = sharedClients.get(key);
+    if (!client) {
+        client = new TcpClient(options);
+        sharedClients.set(key, client);
+    }
+    return client;
 }
-/** Close shared client */
+/** Close all shared clients */
 export function closeSharedTcpClient() {
-    if (sharedClient) {
-        sharedClient.close();
-        sharedClient = null;
+    for (const client of sharedClients.values()) {
+        client.close();
     }
+    sharedClients.clear();
 }

package/dist/client/tcp/types.d.ts

@@ -2,6 +2,17 @@
  * TCP Client Types
  * Type definitions for TCP connection management
  */
+/**
+ * TLS options for client connections.
+ * `true` enables TLS with system CA verification; the object form allows
+ * trusting a custom CA (self-signed server cert) or disabling verification.
+ */
+export interface ClientTlsOptions {
+    /** Verify the server certificate (default: true). Set false for self-signed in dev. */
+    rejectUnauthorized?: boolean;
+    /** Path to a PEM CA certificate to trust (e.g. the self-signed server cert) */
+    caFile?: string;
+}
 /** Connection options */
 export interface ConnectionOptions {
     /** Server host */
@@ -10,6 +21,8 @@ export interface ConnectionOptions {
     port: number;
     /** Auth token */
     token?: string;
+    /** Enable TLS: true (system CAs) or per-connection TLS options (default: false) */
+    tls?: boolean | ClientTlsOptions;
     /** Max reconnection attempts (default: Infinity) */
     maxReconnectAttempts?: number;
     /** Initial reconnect delay in ms (default: 100) */

package/dist/client/tcp/types.js

@@ -7,6 +7,7 @@ export const DEFAULT_CONNECTION = {
     host: 'localhost',
     port: 6789,
     token: '',
+    tls: false,
     maxReconnectAttempts: Infinity,
     reconnectDelay: 100,
     maxReconnectDelay: 30000,

package/dist/client/tcpPool.js

@@ -20,6 +20,7 @@ export class TcpConnectionPool {
             host: options.host ?? 'localhost',
             port: options.port ?? 6789,
             token: options.token ?? '',
+            tls: options.tls ?? false,
             poolSize,
             maxReconnectAttempts: options.maxReconnectAttempts ?? Infinity,
             reconnectDelay: options.reconnectDelay ?? 100,
@@ -39,6 +40,7 @@ export class TcpConnectionPool {
                 host: this.options.host,
                 port: this.options.port,
                 token: this.options.token,
+                tls: this.options.tls,
                 maxReconnectAttempts: this.options.maxReconnectAttempts,
                 reconnectDelay: this.options.reconnectDelay,
                 maxReconnectDelay: this.options.maxReconnectDelay,
@@ -49,6 +51,11 @@ export class TcpConnectionPool {
                 maxPingFailures: this.options.maxPingFailures,
                 maxCommandTimeouts: this.options.maxCommandTimeouts,
             });
+            // Socket-level errors (e.g. TLS handshake failures, protocol garbage) are
+            // emitted as 'error' events; without a listener EventEmitter would throw
+            // and crash the process. Commands are still settled via the close/timeout
+            // paths, so observing the error here is enough.
+            client.on('error', () => { });
             this.clients.push(client);
         }
     }
@@ -169,7 +176,10 @@ function getPoolKey(options) {
     const token = options?.token ?? '';
     // Include poolSize and token hash to prevent sharing pools with different configs
     const tokenHash = token ? String(Number(Bun.hash(token)) & 0xffff) : '0';
-    return `${host}:${port}:${poolSize}:${tokenHash}`;
+    // TLS config must differentiate pools too: a TLS pool and a plaintext pool
+    // to the same host:port are NOT interchangeable.
+    const tlsKey = options?.tls ? JSON.stringify(options.tls) : '0';
+    return `${host}:${port}:${poolSize}:${tokenHash}:${tlsKey}`;
 }
 /** Get or create shared connection pool */
 export function getSharedPool(options) {

package/dist/client/types.d.ts

@@ -360,6 +360,12 @@ export interface JobOptions {
     /** Debounce configuration */
     debounce?: DebounceOptions;
 }
+/**
+ * TLS options for client connections — single definition lives in tcp/types
+ * to prevent drift between the public and internal ConnectionOptions.
+ */
+export type { ClientTlsOptions } from './tcp/types';
+import type { ClientTlsOptions } from './tcp/types';
 /** Connection options for TCP mode */
 export interface ConnectionOptions {
     /** Server host (default: localhost, ignored if socketPath is set) */
@@ -368,6 +374,8 @@ export interface ConnectionOptions {
     port?: number;
     /** Unix socket path (takes priority over host/port) */
     socketPath?: string;
+    /** Enable TLS to the server: true (system CAs) or custom options (default: off) */
+    tls?: boolean | ClientTlsOptions;
     /** Auth token */
     token?: string;
     /** Connection pool size for parallel operations (default: 1, set >1 to enable pooling) */

package/dist/client/worker/worker.js

@@ -44,6 +44,7 @@ function createTcpPool(opts, concurrency) {
         host: connOpts.host ?? 'localhost',
         port: connOpts.port ?? 6789,
         token,
+        tls: connOpts.tls,
         poolSize,
         pingInterval: connOpts.pingInterval,
         commandTimeout: connOpts.commandTimeout,

package/dist/config/index.d.ts

@@ -5,5 +5,5 @@
 export { defineConfig } from './types';
 export type { BunqueueConfig } from './types';
 export { loadConfigFile } from './loader';
-export { resolveServerConfig, resolveCloudConfig, resolveBackupConfig } from './resolve';
+export { resolveServerConfig, resolveCloudConfig, resolveBackupConfig, resolveTlsServerOptions, } from './resolve';
 export type { ResolvedConfig } from './resolve';

package/dist/config/index.js

@@ -4,4 +4,4 @@
  */
 export { defineConfig } from './types';
 export { loadConfigFile } from './loader';
-export { resolveServerConfig, resolveCloudConfig, resolveBackupConfig } from './resolve';
+export { resolveServerConfig, resolveCloudConfig, resolveBackupConfig, resolveTlsServerOptions, } from './resolve';

package/dist/config/resolve.d.ts

@@ -12,6 +12,8 @@ export interface ResolvedConfig {
     hostname: string;
     tcpSocketPath: string | undefined;
     httpSocketPath: string | undefined;
+    tlsCertFile: string | undefined;
+    tlsKeyFile: string | undefined;
     authTokens: string[];
     dataPath: string | undefined;
     corsOrigins: string[];
@@ -22,6 +24,18 @@ export interface ResolvedConfig {
 }
 /** Resolve server config: config file > env vars > defaults */
 export declare function resolveServerConfig(fileConfig: BunqueueConfig | null): ResolvedConfig;
+/**
+ * Resolve server TLS options from resolved config. Returns null when TLS is
+ * not configured; throws when only one of cert/key is set (fail fast at
+ * startup rather than serving plaintext when the operator expected TLS).
+ */
+export declare function resolveTlsServerOptions(config: {
+    tlsCertFile?: string;
+    tlsKeyFile?: string;
+}): {
+    certFile: string;
+    keyFile: string;
+} | null;
 /** Resolve cloud config: config file > env vars. Returns null if disabled. */
 export declare function resolveCloudConfig(fileConfig: BunqueueConfig | null, dataPath?: string): CloudConfig | null;
 /** Resolve S3 backup config: config file > env vars */

package/dist/config/resolve.js

@@ -14,6 +14,8 @@ export function resolveServerConfig(fileConfig) {
         hostname: fc?.server?.host ?? Bun.env.HOST ?? '0.0.0.0',
         tcpSocketPath: fc?.server?.tcpSocketPath ?? Bun.env.TCP_SOCKET_PATH,
         httpSocketPath: fc?.server?.httpSocketPath ?? Bun.env.HTTP_SOCKET_PATH,
+        tlsCertFile: fc?.server?.tlsCertFile ?? Bun.env.TLS_CERT_FILE,
+        tlsKeyFile: fc?.server?.tlsKeyFile ?? Bun.env.TLS_KEY_FILE,
         authTokens: fc?.auth?.tokens ?? Bun.env.AUTH_TOKENS?.split(',').filter(Boolean) ?? [],
         dataPath: fc?.storage?.dataPath ??
             Bun.env.BUNQUEUE_DATA_PATH ??
@@ -28,6 +30,23 @@ export function resolveServerConfig(fileConfig) {
         statsIntervalMs: fc?.timeouts?.stats ?? parseInt(Bun.env.STATS_INTERVAL_MS ?? '300000', 10),
     };
 }
+/**
+ * Resolve server TLS options from resolved config. Returns null when TLS is
+ * not configured; throws when only one of cert/key is set (fail fast at
+ * startup rather than serving plaintext when the operator expected TLS).
+ */
+export function resolveTlsServerOptions(config) {
+    const { tlsCertFile, tlsKeyFile } = config;
+    if (!tlsCertFile && !tlsKeyFile)
+        return null;
+    if (!tlsKeyFile) {
+        throw new Error('TLS misconfigured: tlsCertFile is set but tlsKeyFile (TLS_KEY_FILE) is missing');
+    }
+    if (!tlsCertFile) {
+        throw new Error('TLS misconfigured: tlsKeyFile is set but tlsCertFile (TLS_CERT_FILE) is missing');
+    }
+    return { certFile: tlsCertFile, keyFile: tlsKeyFile };
+}
 /** Resolve cloud config: config file > env vars. Returns null if disabled. */
 export function resolveCloudConfig(fileConfig, dataPath) {
     const fc = fileConfig?.cloud;

package/dist/config/types.d.ts

@@ -10,6 +10,10 @@ export interface BunqueueConfig {
         host?: string;
         tcpSocketPath?: string;
         httpSocketPath?: string;
+        /** Path to PEM certificate file — enables native TLS on TCP + HTTP (with tlsKeyFile) */
+        tlsCertFile?: string;
+        /** Path to PEM private key file — enables native TLS on TCP + HTTP (with tlsCertFile) */
+        tlsKeyFile?: string;
     };
     auth?: {
         tokens?: string[];

package/dist/infrastructure/server/http.d.ts

@@ -5,6 +5,7 @@
 import type { Server, ServerWebSocket } from 'bun';
 import type { QueueManager } from '../../application/queueManager';
 import { type WsData } from './wsHandler';
+import { type TlsServerOptions } from './tls';
 /** HTTP Server configuration */
 export interface HttpServerConfig {
     port?: number;
@@ -13,6 +14,8 @@ export interface HttpServerConfig {
     authTokens?: string[];
     corsOrigins?: string[];
     requireAuthForMetrics?: boolean;
+    /** Native TLS termination (https/wss). Protocol and routes are unchanged. */
+    tls?: TlsServerOptions;
 }
 /**
  * Create and start HTTP server

package/dist/infrastructure/server/http.js

@@ -10,6 +10,7 @@ import { SseHandler } from './sseHandler';
 import { WsHandler } from './wsHandler';
 import { jsonResponse, corsResponse, healthEndpoint, gcEndpoint, heapStatsEndpoint, statsEndpoint, metricsEndpoint, dashboardOverviewEndpoint, dashboardQueuesEndpoint, dashboardQueueDetailEndpoint, } from './httpEndpoints';
 import { routeJobRoutes } from './httpRouteJobs';
+import { loadTlsOptions } from './tls';
 import { routeQueueRoutes } from './httpRouteQueues';
 import { routeQueueConfigRoutes } from './httpRouteQueueConfig';
 import { routeResourceRoutes } from './httpRouteResources';
@@ -202,15 +203,22 @@ export function createHttpServer(queueManager, config) {
             });
         },
     };
-    // Create server
+    // Create server (validate TLS files BEFORE binding, fail fast on bad paths)
+    const tlsOptions = config.tls ? loadTlsOptions(config.tls) : undefined;
     let server;
     if (config.socketPath) {
-        server = Bun.serve({ unix: config.socketPath, fetch, websocket });
+        server = Bun.serve({
+            unix: config.socketPath,
+            ...(tlsOptions && { tls: tlsOptions }),
+            fetch,
+            websocket,
+        });
     }
     else {
         server = Bun.serve({
             hostname: config.hostname ?? '0.0.0.0',
             port: config.port ?? 6790,
+            ...(tlsOptions && { tls: tlsOptions }),
             fetch,
             websocket,
         });

package/dist/infrastructure/server/tcp.d.ts

@@ -9,6 +9,7 @@ import { type HandlerContext } from './handler';
 import { FrameParser, type ConnectionState } from './protocol';
 import { Semaphore } from '../../shared/semaphore';
 import { SocketWriteQueue } from './socketWriteQueue';
+import { type TlsServerOptions } from './tls';
 /** TCP Server configuration */
 export interface TcpServerConfig {
     /** TCP port */
@@ -29,6 +30,11 @@ export interface TcpServerConfig {
      * Mainly for tests.
      */
     maxWriteQueueBytes?: number;
+    /**
+     * Native TLS termination. When set, the server only accepts TLS clients —
+     * the msgpack protocol is unchanged, only the transport is wrapped.
+     */
+    tls?: TlsServerOptions;
 }
 /** Per-connection data */
 interface ConnectionData {

package/dist/infrastructure/server/tcp.js

@@ -11,6 +11,7 @@ import { getRateLimiter } from './rateLimiter';
 import { pack, unpack } from 'msgpackr';
 import { Semaphore, withSemaphore } from '../../shared/semaphore';
 import { SocketWriteQueue } from './socketWriteQueue';
+import { loadTlsOptions } from './tls';
 /** Max concurrent commands per connection for pipelining */
 const MAX_CONCURRENT_PER_CONNECTION = 50;
 /**
@@ -236,10 +237,13 @@ export function createTcpServer(queueManager, config) {
             socket.data.writeQueue.flush(socket);
         },
     };
-    // Create TCP server
+    // Create TCP server (validate TLS files BEFORE binding the port, so a bad
+    // path doesn't leave a half-started listener behind)
+    const tlsOptions = config.tls ? loadTlsOptions(config.tls) : undefined;
     const server = Bun.listen({
         hostname: config.hostname ?? '0.0.0.0',
         port: config.port ?? 6789,
+        ...(tlsOptions && { tls: tlsOptions }),
         socket: socketHandlers,
     });
     return {

package/dist/infrastructure/server/tls.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Server TLS options
+ * Shared by the TCP (Bun.listen) and HTTP (Bun.serve) servers.
+ */
+import type { BunFile } from 'bun';
+/** TLS configuration for a server (paths to PEM files) */
+export interface TlsServerOptions {
+    /** Path to the PEM certificate (or full chain) file */
+    certFile: string;
+    /** Path to the PEM private key file */
+    keyFile: string;
+}
+/**
+ * Validate cert/key paths and build the `tls` option object for
+ * Bun.listen/Bun.serve. Fails fast with a descriptive error so a typo in a
+ * path surfaces at startup instead of as an opaque handshake failure.
+ */
+export declare function loadTlsOptions(tls: TlsServerOptions): {
+    cert: BunFile;
+    key: BunFile;
+};

package/dist/infrastructure/server/tls.js

@@ -0,0 +1,19 @@
+/**
+ * Server TLS options
+ * Shared by the TCP (Bun.listen) and HTTP (Bun.serve) servers.
+ */
+import { existsSync } from 'node:fs';
+/**
+ * Validate cert/key paths and build the `tls` option object for
+ * Bun.listen/Bun.serve. Fails fast with a descriptive error so a typo in a
+ * path surfaces at startup instead of as an opaque handshake failure.
+ */
+export function loadTlsOptions(tls) {
+    if (!existsSync(tls.certFile)) {
+        throw new Error(`TLS cert file not found: ${tls.certFile}`);
+    }
+    if (!existsSync(tls.keyFile)) {
+        throw new Error(`TLS key file not found: ${tls.keyFile}`);
+    }
+    return { cert: Bun.file(tls.certFile), key: Bun.file(tls.keyFile) };
+}

package/dist/main.js

@@ -48,7 +48,7 @@ import { VERSION } from './shared/version';
 import { S3BackupManager } from './infrastructure/backup';
 import { CloudAgent } from './infrastructure/cloud';
 import { SHARD_COUNT } from './shared/hash';
-import { loadConfigFile, resolveServerConfig, resolveCloudConfig, resolveBackupConfig, } from './config';
+import { loadConfigFile, resolveServerConfig, resolveCloudConfig, resolveBackupConfig, resolveTlsServerOptions, } from './config';
 export { defineConfig } from './config';
 /** Print startup banner */
 function printBanner(config, cloudUrl) {
@@ -82,6 +82,7 @@ ${dim}────────────────────────
   ${green}●${reset} HTTP   ${httpDisplay}
   ${yellow}●${reset} Socket ${socketDisplay}
   ${yellow}●${reset} Data   ${config.dataPath ?? 'in-memory'}
+  ${yellow}●${reset} TLS    ${config.tlsCertFile ? `${green}enabled${reset}` : `${dim}disabled${reset}`}
   ${yellow}●${reset} Auth   ${config.authTokens.length > 0 ? `${green}enabled${reset}` : `${dim}disabled${reset}`}
   ${yellow}●${reset} S3 Backup ${config.s3BackupEnabled ? `${green}enabled${reset}` : `${dim}disabled${reset}`}
   ${yellow}●${reset} Cloud  ${cloudUrl ? `${green}enabled${reset} ${dim}→ ${cloudUrl}${reset}` : `${dim}disabled${reset}`}
@@ -108,6 +109,15 @@ async function startServer() {
     }
     // Resolve cloud config
     const cloudConfig = resolveCloudConfig(fileConfig, config.dataPath);
+    // Resolve TLS config — fail fast on partial cert/key before binding anything
+    let tlsConfig;
+    try {
+        tlsConfig = resolveTlsServerOptions(config);
+    }
+    catch (err) {
+        serverLog.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
     printBanner(config, cloudConfig?.url);
     // Create queue manager
     const queueManager = new QueueManager({
@@ -118,6 +128,7 @@ async function startServer() {
         port: config.tcpPort,
         hostname: config.hostname,
         authTokens: config.authTokens,
+        ...(tlsConfig && { tls: tlsConfig }),
     });
     // Start HTTP server
     const httpServer = createHttpServer(queueManager, {
@@ -126,6 +137,7 @@ async function startServer() {
         authTokens: config.authTokens,
         corsOrigins: config.corsOrigins,
         requireAuthForMetrics: config.requireAuthForMetrics,
+        ...(tlsConfig && { tls: tlsConfig }),
     });
     // Initialize S3 backup manager
     let backupManager = null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bunqueue",
-  "version": "2.8.7",
+  "version": "2.8.8",
   "description": "High-performance job queue for Bun & AI agents. SQLite persistence, cron scheduling, priorities, retries, DLQ, webhooks, native MCP server. Zero external dependencies.",
   "type": "module",
   "main": "dist/main.js",