remoteingress/readme.md

# @serve.zone/remoteingress

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`, run the following command in your terminal:

```sh
npm install @serve.zone/remoteingress
```

This command will download and install the remoteingress package and its dependencies into your project.

## Usage

`@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.

### Prerequisites

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.

### Importing and Initializing Connectors

`@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({
  tlsOptions: {
    key: fs.readFileSync("<path-to-your-tls/key.pem>"),
    cert: fs.readFileSync("<path-to-your-cert/cert.pem>"),
    // Consider including 'ca' and 'passphrase' if required for your setup
  },
  listenPort: 443 // Example listen port; adjust based on your needs
});
```

#### Setup ConnectorPrivate

`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 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
  }
});
```

### Secure Communication

It's imperative to ensure that the communication between `ConnectorPublic` and `ConnectorPrivate` is secure:

- 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.

### Advanced Usage

Both connectors can be finely tuned:

- **Logging and Monitoring:** Integrate with your existing logging and monitoring systems to keep tabs on tunnel activity, performance metrics, and potential security anomalies.

- **Custom Handlers:** Implement custom traffic handling logic for specialized routing, filtering, or protocol-specific processing.

- **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

This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository. 

**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

### Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.

### Company Information

Task Venture Capital GmbH  
Registered at District court Bremen HRB 35230 HB, Germany

For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.