From c8fe27143c0a7e6f092e3f7106ddbf40f2796a31 Mon Sep 17 00:00:00 2001 From: Philipp Kunz Date: Sun, 14 Apr 2024 03:40:55 +0200 Subject: [PATCH] fix(core): update --- npmextra.json | 19 +++++---- package.json | 21 ++++++---- readme.md | 85 ++++++++++++++++++++++++---------------- ts/00_commitinfo_data.ts | 4 +- ts/connector.public.ts | 2 +- 5 files changed, 80 insertions(+), 51 deletions(-) diff --git a/npmextra.json b/npmextra.json index 784fd04..91d3087 100644 --- a/npmextra.json +++ b/npmextra.json @@ -5,7 +5,7 @@ "githost": "code.foss.global", "gitscope": "serve.zone", "gitrepo": "remoteingress", - "description": "Provides a service for creating private tunnels and reaching private clusters from the outside as part of the @serve.zone stack.", + "description": "Provides a service for creating private tunnels and reaching private clusters from the outside, facilitating secure remote access as part of the @serve.zone stack.", "npmPackagename": "@serve.zone/remoteingress", "license": "MIT", "projectDomain": "serve.zone", @@ -13,13 +13,18 @@ "remote access", "private tunnels", "network security", - "TLS", + "TLS encryption", "connector", - "serve.zone", - "private clusters", - "public access", - "TypeScript", - "node.js" + "serve.zone stack", + "private clusters access", + "public access management", + "TypeScript application", + "node.js package", + "secure communications", + "TLS/SSL certificates", + "development tools", + "software development", + "private network integration" ] } }, diff --git a/package.json b/package.json index bc5a8ec..1e99a2d 100644 --- a/package.json +++ b/package.json @@ -2,7 +2,7 @@ "name": "@serve.zone/remoteingress", "version": "1.0.3", "private": false, - "description": "Provides a service for creating private tunnels and reaching private clusters from the outside as part of the @serve.zone stack.", + "description": "Provides a service for creating private tunnels and reaching private clusters from the outside, facilitating secure remote access as part of the @serve.zone stack.", "main": "dist_ts/index.js", "typings": "dist_ts/index.d.ts", "type": "module", @@ -51,12 +51,17 @@ "remote access", "private tunnels", "network security", - "TLS", + "TLS encryption", "connector", - "serve.zone", - "private clusters", - "public access", - "TypeScript", - "node.js" + "serve.zone stack", + "private clusters access", + "public access management", + "TypeScript application", + "node.js package", + "secure communications", + "TLS/SSL certificates", + "development tools", + "software development", + "private network integration" ] -} +} \ No newline at end of file diff --git a/readme.md b/readme.md index 23faa0a..3dc8a0a 100644 --- a/readme.md +++ b/readme.md @@ -1,72 +1,91 @@ # @serve.zone/remoteingress -a remoteingress service for serve.zone + +Provides a service for creating private tunnels and reaching private clusters from the outside as part of the @serve.zone stack. ## Install -To install `@serve.zone/remoteingress`, use the following command in your terminal: + +To install `@serve.zone/remoteingress`, run the following command in your terminal: ```sh npm install @serve.zone/remoteingress ``` -This will download and install the remote ingress service and its dependencies in your project. +This command will download and install the remoteingress package and its dependencies into your project. ## Usage -The `@serve.zone/remoteingress` package is designed to aid in creating secure and private tunnels to private networks, allowing external access to services within a private cluster as part of the @serve.zone stack. To utilize this package, you should have a basic understanding of network protocols and Node.js. -### Getting Started -First, ensure you have [Node.js](https://nodejs.org/) installed on your system and that your project is set up to support TypeScript. +`@serve.zone/remoteingress` is designed to facilitate the creation of secure private tunnels and enable access to private clusters from external sources, offering an integral part of the @serve.zone stack infrastructure. Below, we illustrate how to employ this package within your project, leveraging TypeScript and ESM syntax for modern, type-safe, and modular code. -You will need to import the main components of the package, which are `ConnectorPublic` and `ConnectorPrivate`, depending on the role your application is playing. Typically, `ConnectorPublic` would run on a public server accessible from the internet, while `ConnectorPrivate` runs inside a private network, creating a secure tunnel to the `ConnectorPublic` instance. +### Prerequisites -### Example Setup +Ensure that you have Node.js and TypeScript installed in your environment. Your project should be set up with TypeScript support, and you might want to familiarize yourself with basic networking concepts and TLS/SSL for secure communication. -#### Using `ConnectorPublic` -The `ConnectorPublic` part of the module is responsible for listening for incoming tunnel connections and forwarding requests to and from the `ConnectorPrivate` instance. +### Importing and Initializing Connectors -**Example `ConnectorPublic` Usage:** +`@serve.zone/remoteingress` offers two primary components: `ConnectorPublic` and `ConnectorPrivate`. Here's how to use them: + +#### Setup ConnectorPublic + +`ConnectorPublic` acts as a gateway, accepting incoming tunnel connections from `ConnectorPrivate` instances and facilitating secure communication between the internet and your private network. ```typescript import { ConnectorPublic } from '@serve.zone/remoteingress'; // Initialize ConnectorPublic -const publicConnector = new ConnectorPublic(); +const publicConnector = new ConnectorPublic({ + tlsOptions: { + key: fs.readFileSync(""), + cert: fs.readFileSync(""), + // Consider including 'ca' and 'passphrase' if required for your setup + }, + listenPort: 443 // Example listen port; adjust based on your needs +}); ``` -The above code initializes the `ConnectorPublic`, making it listen for incoming tunnel connections. In practical use, you would need to provide configurations, such as SSL certificates, to secure the tunnel communication. +#### Setup ConnectorPrivate -#### Using `ConnectorPrivate` -The `ConnectorPrivate` component establishes a connection to the `ConnectorPublic` and routes traffic between the public interface and the private network. - -**Example `ConnectorPrivate` Usage:** +`ConnectorPrivate` establishes a secure tunnel to `ConnectorPublic`, effectively bridging your internal services with the external point of access. ```typescript import { ConnectorPrivate } from '@serve.zone/remoteingress'; -// Initialize ConnectorPrivate with the host and port of the ConnectorPublic -const privateConnector = new ConnectorPrivate('public.example.com', 4000); +// Initialize ConnectorPrivate pointing to your ConnectorPublic instance +const privateConnector = new ConnectorPrivate({ + publicHost: 'your.public.domain.tld', + publicPort: 443, // Ensure this matches the listening port of ConnectorPublic + tlsOptions: { + // You might want to specify TLS options here, similar to ConnectorPublic + } +}); ``` -This example assumes your `ConnectorPublic` is accessible at `public.example.com` on port `4000`. The `ConnectorPrivate` will establish a secure tunnel to this public endpoint and begin routing traffic. +### Secure Communication -### Securely Setting Up The Tunnel -Security is paramount when creating tunnels that expose private networks. Ensure you use TLS encryption for your tunnels and validate certificates properly. +It's imperative to ensure that the communication between `ConnectorPublic` and `ConnectorPrivate` is secure: -For both `ConnectorPublic` and `ConnectorPrivate`, you'll need to provide paths to your SSL certificate files or use a secure context set up with a recognized Certificate Authority (CA). +- Always use valid TLS certificates. +- Prefer using certificates issued by recognized Certificate Authorities (CA). +- Optionally, configure mutual TLS (mTLS) by requiring client certificates for an added layer of security. -**Security best practices:** +### Advanced Usage -- Always use TLS to encrypt tunnel traffic. -- Ensure your certificates are valid and up-to-date. -- Consider using client certificates for `ConnectorPrivate` to authenticate to `ConnectorPublic`. -- Monitor and possibly rate-limit connections to avoid abuse. +Both connectors can be finely tuned: -### Advanced Configuration -Both `ConnectorPublic` and `ConnectorPrivate` allow for advanced configurations and handling to adjust to specific requirements, such as custom routing, handling different types of traffic (e.g., HTTP, HTTPS), and integrating with existing systems. +- **Logging and Monitoring:** Integrate with your existing logging and monitoring systems to keep tabs on tunnel activity, performance metrics, and potential security anomalies. -### Conclusion -This module simplifies the process of setting up secure, remote ingress into private networks. By leveraging TLS and careful configuration, you can safely expose services within a private cluster to the outside world. Always prioritize security in your setup to protect your infrastructure and data. +- **Custom Handlers:** Implement custom traffic handling logic for specialized routing, filtering, or protocol-specific processing. -For more detailed configuration options and advanced use cases, refer to the source code and additional documentation provided in the package. +- **Automation:** Automate the deployment and scaling of both `ConnectorPublic` and `ConnectorPrivate` instances using infrastructure-as-code (IAC) tools and practices, ensuring that your tunneling infrastructure can dynamically adapt to the ever-changing needs of your services. + +### Example Scenarios + +1. **Securing Application APIs:** Use `@serve.zone/remoteingress` to expose private APIs to your frontend deployed on a public cloud, ensuring that only your infrastructure can access these endpoints. + +2. **Remote Database Access:** Securely access databases within a private VPC from your local development machine without opening direct access to the internet. + +3. **Service Mesh Integration:** Integrate `@serve.zone/remoteingress` as part of a service mesh setup to securely connect services across multiple clusters with robust identity and encryption at the tunnel level. + +For detailed documentation, API references, and additional use cases, please refer to the inline documentation and source code within the package. Always prioritize security and robustness when dealing with network ingress to protect your infrastructure and data from unauthorized access and threats. ## License and Legal Information diff --git a/ts/00_commitinfo_data.ts b/ts/00_commitinfo_data.ts index 93850f4..5280de1 100644 --- a/ts/00_commitinfo_data.ts +++ b/ts/00_commitinfo_data.ts @@ -3,6 +3,6 @@ */ export const commitinfo = { name: '@serve.zone/remoteingress', - version: '1.0.3', - description: 'Provides a service for creating private tunnels and reaching private clusters from the outside as part of the @serve.zone stack.' + version: '1.0.4', + description: 'Provides a service for creating private tunnels and reaching private clusters from the outside, facilitating secure remote access as part of the @serve.zone stack.' } diff --git a/ts/connector.public.ts b/ts/connector.public.ts index cff8abe..5f47c12 100644 --- a/ts/connector.public.ts +++ b/ts/connector.public.ts @@ -1,6 +1,6 @@ import * as plugins from './plugins.js'; -class PublicRemoteConnector { +export class ConnectorPublic { private tunnel: plugins.tls.TLSSocket | null = null; constructor() {