feat: implement TLS support for secure connections and HTTP to HTTPS redirection

Author: benjinus

.env.example

@@ -8,6 +8,18 @@ TELAGENT_API_PORT=9529
 # Required on cloud/public deployments so other nodes can reach you.
 # TELAGENT_PUBLIC_URL=http://your-server-ip:9529
 
+# --------------------------------------------------------------------
+# TLS / HTTPS (optional — set both CERT and KEY to enable)
+# When enabled, the node serves HTTPS on TLS_PORT (default 9443)
+# and the HTTP port (API_PORT) becomes a 301 redirect to HTTPS.
+# Without these, the node serves plain HTTP (use Caddy/nginx for TLS).
+# Generate self-signed cert for testing:
+# openssl req -x509 -newkey rsa:2048 -nodes -keyout /tmp/key.pem -out /tmp/cert.pem -days 365 -subj '/CN=localhost'
+# --------------------------------------------------------------------
+# TELAGENT_TLS_CERT=/path/to/cert.pem
+# TELAGENT_TLS_KEY=/path/to/key.pem
+# TELAGENT_TLS_PORT=9443
+
 # --------------------------------------------------------------------
 # TelAgent storage
 # --------------------------------------------------------------------

packages/node/src/api/server.ts

@@ -1,4 +1,6 @@
-import { createServer, type IncomingMessage, type Server } from 'node:http';
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http';
+import { createServer as createHttpsServer, type Server as HttpsServer } from 'node:https';
+import { readFileSync } from 'node:fs';
 import { performance } from 'node:perf_hooks';
 
 import { ErrorCodes, TelagentError } from '@telagent/protocol';
@@ -96,18 +98,15 @@ function requireGlobalAuth(req: IncomingMessage, pathname: string, ctx: RuntimeC
 
 export class ApiServer {
   private server: Server | null = null;
+  private secureServer: HttpsServer | null = null;
   private readonly router: Router;
 
   constructor(private readonly ctx: RuntimeContext) {
     this.router = buildRouter(ctx);
   }
 
-  async start(): Promise<void> {
-    if (this.server) {
-      return;
-    }
-
-    this.server = createServer(async (req, res) => {
+  private createRequestHandler() {
+    return async (req: IncomingMessage, res: ServerResponse) => {
       const parsedUrl = new URL(req.url || '/', 'http://127.0.0.1');
       const startedAt = performance.now();
       res.once('finish', () => {
@@ -161,25 +160,68 @@ export class ApiServer {
         const internal = error instanceof TelagentError ? error : new TelagentError(ErrorCodes.INTERNAL, error instanceof Error ? error.message : 'Unexpected error');
         problem(res, internal.toProblem(req.url));
       }
-    });
+    };
+  }
 
-    await new Promise<void>((resolve) => {
-      this.server!.listen(this.ctx.config.port, this.ctx.config.host, resolve);
-    });
+  async start(): Promise<void> {
+    if (this.server || this.secureServer) {
+      return;
+    }
+
+    const { tls } = this.ctx.config;
+
+    if (tls) {
+      // ── HTTPS mode: main traffic on HTTPS, HTTP redirects to HTTPS ──
+      const cert = readFileSync(tls.certPath);
+      const key = readFileSync(tls.keyPath);
+
+      this.secureServer = createHttpsServer({ cert, key }, this.createRequestHandler());
+      await new Promise<void>((resolve) => {
+        this.secureServer!.listen(tls.httpsPort, this.ctx.config.host, resolve);
+      });
+
+      // HTTP → HTTPS redirect server
+      const httpsPort = tls.httpsPort;
+      const redirectHost = this.ctx.config.host;
+      this.server = createServer((req, res) => {
+        const host = req.headers.host?.replace(/:\d+$/, '') || redirectHost;
+        const location = `https://${host}${httpsPort === 443 ? '' : ':' + httpsPort}${req.url || '/'}`;
+        res.writeHead(301, { Location: location });
+        res.end();
+      });
+      await new Promise<void>((resolve) => {
+        this.server!.listen(this.ctx.config.port, this.ctx.config.host, resolve);
+      });
+    } else {
+      // ── Plain HTTP mode (default, unchanged) ──
+      this.server = createServer(this.createRequestHandler());
+      await new Promise<void>((resolve) => {
+        this.server!.listen(this.ctx.config.port, this.ctx.config.host, resolve);
+      });
+    }
   }
 
   async stop(): Promise<void> {
-    if (!this.server) {
-      return;
+    const closeServer = (s: Server | HttpsServer) =>
+      new Promise<void>((resolve) => { s.close(() => resolve()); });
+
+    const tasks: Promise<void>[] = [];
+    if (this.secureServer) {
+      tasks.push(closeServer(this.secureServer));
+      this.secureServer = null;
+    }
+    if (this.server) {
+      tasks.push(closeServer(this.server));
+      this.server = null;
     }
-    const current = this.server;
-    this.server = null;
-    await new Promise<void>((resolve) => {
-      current.close(() => resolve());
-    });
+    await Promise.all(tasks);
   }
 
   get httpServer(): Server | null {
     return this.server;
   }
+
+  get httpsServer(): HttpsServer | null {
+    return this.secureServer;
+  }
 }

packages/node/src/api/types.ts

@@ -15,10 +15,17 @@ import type { PeerProfileRepository } from '../storage/peer-profile-repository.j
 import type { ApiProxyService } from '../services/api-proxy-service.js';
 import type { EventPushService } from '../services/event-push-service.js';
 
+export interface TlsServerConfig {
+  certPath: string;
+  keyPath: string;
+  httpsPort: number;
+}
+
 export interface ApiServerConfig {
   host: string;
   port: number;
   publicUrl?: string;
+  tls?: TlsServerConfig;
 }
 
 export interface RuntimeContext {

packages/node/src/app.ts

@@ -281,6 +281,11 @@ export class TelagentNode {
         host: this.config.host,
         port: this.config.port,
         publicUrl: this.config.publicUrl,
+        tls: this.config.tls ? {
+          certPath: this.config.tls.certPath,
+          keyPath: this.config.tls.keyPath,
+          httpsPort: this.config.tls.httpsPort,
+        } : undefined,
       },
       identityService: this.identityService,
       groupService: this.groupService,

packages/node/src/config.ts

@@ -1,3 +1,5 @@
+import { accessSync, constants as fsConstants } from 'node:fs';
+
 import { ChainConfigSchema, type ChainConfig } from './services/chain-config.js';
 import {
   parseOwnerMode,
@@ -53,6 +55,12 @@ export interface OwnerConfig {
   privateConversations: string[];
 }
 
+export interface TlsConfig {
+  certPath: string;
+  keyPath: string;
+  httpsPort: number;
+}
+
 export interface ApiProxyConfig {
   enabled: boolean;
   gatewayEnabled: boolean;
@@ -65,6 +73,7 @@ export interface AppConfig {
   host: string;
   port: number;
   publicUrl?: string;
+  tls?: TlsConfig;
   paths: TelagentStoragePaths;
   mailboxCleanupIntervalSec: number;
   mailboxStore: MailboxStoreConfig;
@@ -107,6 +116,27 @@ export function loadConfigFromEnv(): AppConfig {
   const host = process.env.TELAGENT_API_HOST || '127.0.0.1';
   const port = Number(process.env.TELAGENT_API_PORT || 9529);
 
+  // ── TLS (optional) ──────────────────────────────────────
+  let tls: TlsConfig | undefined;
+  const tlsCert = process.env.TELAGENT_TLS_CERT?.trim();
+  const tlsKey = process.env.TELAGENT_TLS_KEY?.trim();
+  if (tlsCert && tlsKey) {
+    for (const p of [tlsCert, tlsKey]) {
+      try {
+        accessSync(p, fsConstants.R_OK);
+      } catch {
+        throw new Error(`TLS file not readable: ${p}`);
+      }
+    }
+    tls = {
+      certPath: tlsCert,
+      keyPath: tlsKey,
+      httpsPort: Number(process.env.TELAGENT_TLS_PORT || 9443),
+    };
+  } else if (tlsCert || tlsKey) {
+    throw new Error('Both TELAGENT_TLS_CERT and TELAGENT_TLS_KEY must be set to enable TLS');
+  }
+
   const chain = ChainConfigSchema.parse({
     rpcUrl: process.env.TELAGENT_CHAIN_RPC_URL,
     chainId: Number(process.env.TELAGENT_CHAIN_ID || 7625),
@@ -178,6 +208,7 @@ export function loadConfigFromEnv(): AppConfig {
     host,
     port,
     publicUrl,
+    tls,
     paths,
     mailboxCleanupIntervalSec: Number(process.env.TELAGENT_MAILBOX_CLEANUP_INTERVAL_SEC || 60),
     mailboxStore,

packages/node/src/daemon.ts

@@ -19,7 +19,12 @@ async function main(): Promise<void> {
   const node = new TelagentNode(config);
 
   await node.start();
-  logger.info(`telagent node started at http://${config.host}:${config.port}`);
+  if (config.tls) {
+    logger.info(`telagent node started at https://${config.host}:${config.tls.httpsPort}`);
+    logger.info(`http://${config.host}:${config.port} → redirect to HTTPS`);
+  } else {
+    logger.info(`telagent node started at http://${config.host}:${config.port}`);
+  }
   logger.info(`chainId: ${config.chain.chainId}`);
 
   const shutdown = async (signal: string): Promise<void> => {