@tmlmobilidade/go-clients-ssh 20260828.1636.54

package/dist/client.d.ts

@@ -0,0 +1,45 @@
+import { type Server } from 'node:net';
+import { type ForwardOptions, type ServerOptions, type SshOptions, type TunnelOptions } from 'tunnel-ssh';
+export interface SshConfig {
+    forwardOptions: ForwardOptions;
+    serverOptions: ServerOptions;
+    sshOptions: SshOptions;
+    tunnelOptions: TunnelOptions;
+}
+export interface SshTunnelOptions {
+    maxRetries?: number;
+}
+export declare class SshTunnel {
+    private _server;
+    private config;
+    private onDisconnect?;
+    private options;
+    private retries;
+    constructor(config: SshConfig, options?: SshTunnelOptions, onDisconnect?: () => void);
+    get server(): Server | undefined;
+    /**
+     * Establishes an SSH tunnel connection using the provided configuration options.
+     * @throws Throws an error if the connection fails after the maximum number of retries.
+     * @remarks
+     * - The method attempts to create an SSH tunnel using the `createTunnel` function with the specified options.
+     * - If the connection is successful, it logs the connected host port and sets up an error listener on the server.
+     * - If the connection fails, it retries the connection up to a maximum number of retries specified in the options.
+     * @example ```typescript
+     * const SshTunnel = new SshTunnel(config);
+     * SshTunnel.connect();
+     * ```
+     */
+    connect(): any;
+    /**
+     * Disconnects the SSH tunnel by closing the server.
+     * @returns A promise that resolves when the server is successfully closed.
+     * @throws Will log an error message if the server fails to close.
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Reconnects the SSH tunnel by first disconnecting and then connecting again.
+     * This method ensures that the connection is reset.
+     * @returns A promise that resolves when the reconnection process is complete.
+     */
+    reconnect(): Promise<void>;
+}

package/dist/client.js

@@ -0,0 +1,92 @@
+/* * */
+import { Logger } from '@tmlmobilidade/logger';
+import { createTunnel } from 'tunnel-ssh';
+/* * */
+export class SshTunnel {
+    _server;
+    config;
+    onDisconnect;
+    options;
+    retries = 0;
+    constructor(config, options, onDisconnect) {
+        this.config = config;
+        this.onDisconnect = onDisconnect;
+        if (options)
+            this.options = options;
+    }
+    get server() {
+        return this._server;
+    }
+    /**
+     * Establishes an SSH tunnel connection using the provided configuration options.
+     * @throws Throws an error if the connection fails after the maximum number of retries.
+     * @remarks
+     * - The method attempts to create an SSH tunnel using the `createTunnel` function with the specified options.
+     * - If the connection is successful, it logs the connected host port and sets up an error listener on the server.
+     * - If the connection fails, it retries the connection up to a maximum number of retries specified in the options.
+     * @example ```typescript
+     * const SshTunnel = new SshTunnel(config);
+     * SshTunnel.connect();
+     * ```
+     */
+    async connect() {
+        try {
+            if (this._server) {
+                // If the server is already connected, return it
+                console.log(`⤷ SSH Tunnel already connected.`);
+                return this._server;
+            }
+            const [server] = await createTunnel(this.config.tunnelOptions, this.config.serverOptions, this.config.sshOptions, this.config.forwardOptions);
+            Logger.info({ message: `SSH Tunnel connected to host port ${server.address().port}` });
+            this._server = server;
+            server.on('error', (error) => {
+                Logger.error({ error, message: 'SSH Tunnel Error' });
+            });
+            server.on('close', () => {
+                Logger.info({ message: 'SSH Tunnel closed.' });
+            });
+            return this._server;
+        }
+        catch (error) {
+            if (error.code === 'EADDRINUSE') {
+                Logger.info({ message: `Port "${this.config.serverOptions.port}" already in use. Retrying with a different port...` });
+                this.config.serverOptions.port++;
+                return await this.connect();
+            }
+            else if (this.retries < (this.options?.maxRetries || 3)) {
+                Logger.error({ error, message: 'Failed to connect to SSH Tunnel.' });
+                this.retries++;
+                Logger.info({ message: 'Retrying SSH connection...' });
+                return await this.connect();
+            }
+            else {
+                throw new Error('Error connecting to SSH tunnel', { cause: error });
+            }
+        }
+    }
+    /**
+     * Disconnects the SSH tunnel by closing the server.
+     * @returns A promise that resolves when the server is successfully closed.
+     * @throws Will log an error message if the server fails to close.
+     */
+    async disconnect() {
+        try {
+            this._server?.close();
+            this._server = undefined;
+            this.onDisconnect?.();
+            console.log(`⤷ SSH Tunnel disconnected.`);
+        }
+        catch (error) {
+            console.log(`⤷ ERROR: Failed to disconnect from SSH Tunnel.`, error);
+        }
+    }
+    /**
+     * Reconnects the SSH tunnel by first disconnecting and then connecting again.
+     * This method ensures that the connection is reset.
+     * @returns A promise that resolves when the reconnection process is complete.
+     */
+    async reconnect() {
+        await this.disconnect();
+        await this.connect();
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './client.js';
+export * from './ssh.factory.js';
+export * from './tunnels.js';

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from './client.js';
+export * from './ssh.factory.js';
+export * from './tunnels.js';

package/dist/ssh.factory.d.ts

@@ -0,0 +1,26 @@
+import { SshTunnel } from './client.js';
+export type SshTunnelType = 'CP' | 'GO' | 'PCGI';
+interface SshTunnelFactoryOptions {
+    dstAddr: string;
+    dstPort: number;
+    maxRetries?: number;
+}
+export type SshTunnelFactory = (options: SshTunnelFactoryOptions) => null | SshTunnel;
+/**
+ * Creates an SSH tunnel factory for the given type.
+ *
+ * The returned function reads `{type}_TUNNEL_*` environment variables
+ * and builds an `SshTunnel` when tunneling is enabled.
+ *
+ * Expected environment variables:
+ *   `{type}_TUNNEL_ENABLED` — `"true"` or `"false"`; `"false"` returns `null`
+ *   `{type}_TUNNEL_SSH_HOST`
+ *   `{type}_TUNNEL_SSH_USERNAME`
+ *   `{type}_TUNNEL_SSH_KEY_PATH` (optional)
+ *   `{type}_TUNNEL_SSH_KEY` (optional)
+ *   `SSH_AUTH_SOCK` (optional fallback agent)
+ *
+ * Auth priority: `TUNNEL_SSH_KEY_PATH` > `TUNNEL_SSH_KEY` > `SSH_AUTH_SOCK`.
+ */
+export declare function createSshTunnelFactory(type: SshTunnelType): SshTunnelFactory;
+export {};

package/dist/ssh.factory.js

@@ -0,0 +1,80 @@
+/* * */
+import { randomInt } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { SshTunnel } from './client.js';
+const tunnelCache = new Map();
+/**
+ * Creates an SSH tunnel factory for the given type.
+ *
+ * The returned function reads `{type}_TUNNEL_*` environment variables
+ * and builds an `SshTunnel` when tunneling is enabled.
+ *
+ * Expected environment variables:
+ *   `{type}_TUNNEL_ENABLED` — `"true"` or `"false"`; `"false"` returns `null`
+ *   `{type}_TUNNEL_SSH_HOST`
+ *   `{type}_TUNNEL_SSH_USERNAME`
+ *   `{type}_TUNNEL_SSH_KEY_PATH` (optional)
+ *   `{type}_TUNNEL_SSH_KEY` (optional)
+ *   `SSH_AUTH_SOCK` (optional fallback agent)
+ *
+ * Auth priority: `TUNNEL_SSH_KEY_PATH` > `TUNNEL_SSH_KEY` > `SSH_AUTH_SOCK`.
+ */
+export function createSshTunnelFactory(type) {
+    return (options) => buildSshTunnel(type, options);
+}
+function buildSshTunnel(type, options) {
+    const { dstAddr, dstPort, maxRetries } = options;
+    const env = (name) => process.env[`${type}_${name}`];
+    if (env('TUNNEL_ENABLED') !== 'true') {
+        return null;
+    }
+    if (!env('TUNNEL_SSH_HOST')) {
+        throw new Error(`Missing ${type}_TUNNEL_SSH_HOST environment variable.`);
+    }
+    if (!env('TUNNEL_SSH_USERNAME')) {
+        throw new Error(`Missing ${type}_TUNNEL_SSH_USERNAME environment variable.`);
+    }
+    if (!env('TUNNEL_SSH_KEY_PATH') && !env('TUNNEL_SSH_KEY') && !process.env.SSH_AUTH_SOCK) {
+        throw new Error(`Missing authentication configuration. Please provide ${type}_TUNNEL_SSH_KEY_PATH, ${type}_TUNNEL_SSH_KEY, or ensure SSH_AUTH_SOCK is set.`);
+    }
+    const srcPort = randomInt(8_000, 8_999);
+    const sshConfig = {
+        forwardOptions: {
+            dstAddr: dstAddr,
+            dstPort: dstPort,
+            srcAddr: 'localhost',
+            srcPort: srcPort,
+        },
+        serverOptions: {
+            port: srcPort,
+        },
+        sshOptions: {
+            agent: (env('TUNNEL_SSH_KEY_PATH') || env('TUNNEL_SSH_KEY')) ? undefined : process.env.SSH_AUTH_SOCK,
+            host: env('TUNNEL_SSH_HOST'),
+            keepaliveCountMax: 3,
+            keepaliveInterval: 10_000,
+            port: 22,
+            privateKey: env('TUNNEL_SSH_KEY_PATH')
+                ? readFileSync(env('TUNNEL_SSH_KEY_PATH'))
+                : env('TUNNEL_SSH_KEY')
+                    ? env('TUNNEL_SSH_KEY')
+                    : undefined,
+            username: env('TUNNEL_SSH_USERNAME'),
+        },
+        tunnelOptions: {
+            autoClose: false,
+            reconnectOnError: true,
+        },
+    };
+    const sshOptions = {
+        maxRetries: maxRetries ?? 3,
+    };
+    const cacheKey = `${type}:${dstAddr}:${dstPort}`;
+    const cached = tunnelCache.get(cacheKey);
+    if (cached) {
+        return cached;
+    }
+    const tunnel = new SshTunnel(sshConfig, sshOptions, () => tunnelCache.delete(cacheKey));
+    tunnelCache.set(cacheKey, tunnel);
+    return tunnel;
+}

package/dist/tunnels.d.ts

@@ -0,0 +1,3 @@
+export declare const goSshTunnel: import("./ssh.factory.js").SshTunnelFactory;
+export declare const cpSshTunnel: import("./ssh.factory.js").SshTunnelFactory;
+export declare const pcgiSshTunnel: import("./ssh.factory.js").SshTunnelFactory;

package/dist/tunnels.js

@@ -0,0 +1,6 @@
+/* * */
+import { createSshTunnelFactory } from './ssh.factory.js';
+/* * */
+export const goSshTunnel = createSshTunnelFactory('GO');
+export const cpSshTunnel = createSshTunnelFactory('CP');
+export const pcgiSshTunnel = createSshTunnelFactory('PCGI');

package/package.json

@@ -0,0 +1,49 @@
+{
+	"name": "@tmlmobilidade/go-clients-ssh",
+	"version": "20260828.1636.54",
+	"author": {
+		"email": "iso@tmlmobilidade.pt",
+		"name": "TML-ISO"
+	},
+	"license": "AGPL-3.0-or-later",
+	"homepage": "https://go.tmlmobilidade.pt",
+	"bugs": {
+		"url": "https://github.com/tmlmobilidade/go/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/tmlmobilidade/go.git"
+	},
+	"keywords": [
+		"public transit",
+		"tml",
+		"transportes metropolitanos de lisboa",
+		"go"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"type": "module",
+	"files": [
+		"dist"
+	],
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"scripts": {
+		"build": "tsc && resolve-tspaths",
+		"lint": "eslint ./src/ && tsc --noEmit",
+		"lint:fix": "eslint ./src/ --fix",
+		"watch": "tsc-watch --onSuccess 'resolve-tspaths'"
+	},
+	"dependencies": {
+		"@tmlmobilidade/logger": "*",
+		"tunnel-ssh": "5.2.0"
+	},
+	"devDependencies": {
+		"@tmlmobilidade/go-utils-tsconfig": "*",
+		"@types/node": "26.1.2",
+		"resolve-tspaths": "0.8.23",
+		"tsc-watch": "7.2.1",
+		"typescript": "6.0.3"
+	}
+}