FlyingDarkDevTunnel

Open-source tunneling platform that turns localhost services into secure, policy-aware public endpoints.

How It Works · Architecture · Testing and CI · Runbooks · Owner: xgauravyaduvanshii · Repository Home

---

Platform Story

FlyingDarkDevTunnel is built for teams that need more than a temporary tunnel URL.
It combines data-plane speed, control-plane policy, payment operations, and production-grade runbook discipline in one monorepo.

This project is designed so that each critical behavior has:

• explicit ownership,
• deterministic retry/reconcile paths,
• and measurable operational signals.

Build fast like a developer tool, run safe like production infrastructure.

---

Why Teams Use It

• Ship webhook integrations without deploying staging environments for every branch.
• Expose demo and QA environments safely with auth/IP controls.
• Tunnel raw TCP services for SSH, DB diagnostics, and IoT flows.
• Manage billing entitlements and audit trails from the same platform model.
• Run with operational confidence using dashboards, alerts, and recovery runbooks.

This repository intentionally speaks to multiple personas who collaborate on one shared system model instead of disconnected tools.

---

Capability Matrix

Capability Group	Included
Tunnel Protocols	HTTP, HTTPS, raw TCP
URL Strategy	random URLs, reserved subdomains, custom domains
TLS Modes	edge termination and end-to-end passthrough
Access Controls	JWT auth, basic auth, CIDR allowlist, revocation lists
Inspection	request metadata capture, payload retention controls, replay API
Billing Providers	Stripe, Razorpay, PayPal
Admin Controls	user/org management, entitlement overrides, audit visibility
Reliability Features	retries, dead-letter workflows, replay/reconcile pipelines
Operations	Prometheus, Grafana, alert rules, incident runbooks

---

Localhost to Internet Journey

This request journey is built around strict checkpoints:

• identity and entitlement validation before edge registration,
• relay-side enforcement for host mode, auth, and network policy,
• stream forwarding between relay and agent,
• optional inspection and replay for debugging,
• metrics and audit artifacts for incident response.

---

CLI Experience

Core commands

cd go

# login
go run ./agent login \
  --api http://localhost:4000 \
  --email xgauravyaduvanshii@gmail.com \
  --password yourpassword

# http tunnel
go run ./agent http \
  --api http://localhost:4000 \
  --relay ws://localhost:8081/control \
  --authtoken <authtoken> \
  --tunnel-id <tunnel-uuid> \
  --local http://localhost:3000 \
  --region us

# tcp tunnel
go run ./agent tcp \
  --api http://localhost:4000 \
  --relay ws://localhost:8081/control \
  --authtoken <authtoken> \
  --tunnel-id <tunnel-uuid> \
  --local 127.0.0.1:22 \
  --region us

For multi-tunnel configs:

• ourdomain.yml.example
• go/ourdomain.example.yml

---

Monorepo Architecture

Path	Role
apps/	User/admin console and docs surface
services/	API and workers (billing, inspector, certificates)
go/	Relay edge + agent CLI + shared proto contracts
packages/	Shared config, UI, SDK, lint/type presets
infra/	Docker, migrations, Cloudflare, monitoring
docs/	Design references, runbooks, operational guides
scripts/	Smoke tests, resilience drills, local bootstrap

---

Security and Trust Model

Security is not treated as an add-on; it is encoded in runtime decisions and async pipelines.

Implemented security controls include:

• hashed authtokens and short-lived signed agent tokens,
• token revoke-list checks in control and edge flows,
• relay-side basic auth and CIDR allowlist enforcement,
• signed provider callbacks for billing and certificate events,
• immutable audit integrity verification for sensitive admin actions.

See:

• docs/security-and-tls.md
• docs/certificate-lifecycle.md
• docs/runbooks/certificate-alerts.md

---

Payments and Revenue Operations

Payment architecture is designed for correctness under retries, provider jitter, and delayed settlements.

Current behavior includes:

• real provider mode for Stripe with fallback mock checkout when keys are absent,
• Razorpay and PayPal provider orchestration hooks,
• signed webhook ingestion and replay-safe processing,
• dunning state tracking and finance export packaging workflows.

See:

• docs/billing-providers.md
• docs/runbooks/billing-webhook-slo.md
• services/worker-billing/

---

Reliability and On-Call Operations

Reliability foundation:

• Prometheus and alert rules under infra/monitoring/,
• Grafana provisioning and dashboard JSON committed in-repo,
• integration smoke plus resilience scripts in scripts/,
• runbook-first incident handling for certificate, payment, and security classes.

---

Deployment Blueprint

The platform can run as a managed SaaS stack on Ubuntu VPS with Docker Compose:

• edge relay for ingress and policy gates,
• API and workers for control + async workflows,
• PostgreSQL/Redis/object storage for persistence layers,
• monitoring and alerting for on-call visibility.

---

Quick Start

Prerequisites

• Node.js 20+
• pnpm 10+
• Go 1.18+
• Docker + Docker Compose plugin

Install and run

pnpm install
pnpm dev:infra

Core local endpoints:

• API: http://localhost:4000
• Console: http://localhost:3000
• Docs: http://localhost:3001
• Relay HTTP: http://localhost:8080
• Relay HTTPS: https://localhost:8443
• Grafana: http://localhost:3100
• Prometheus: http://localhost:9090

---

Quality Gates

pnpm lint
pnpm typecheck
pnpm test
pnpm build

cd go
go test ./...
go build -o bin/relay ./relay
go build -o bin/fdt ./agent

Integration tests (API):

DATABASE_URL=postgres://postgres:postgres@127.0.0.1:55432/fdt \
REDIS_URL=redis://127.0.0.1:6379 \
pnpm --filter @fdt/api test:integration

Release quality philosophy:

• code quality checks prevent drift in shared contracts and policies,
• integration gates validate behavior across API, workers, and relay surfaces,
• resilience checks validate recovery workflows before customer-impacting changes ship.

---

Documentation

• docs hub: docs/README.md
• architecture deep dive: docs/architecture.md
• flow diagrams: docs/how-it-works.md
• security and TLS: docs/security-and-tls.md
• billing providers: docs/billing-providers.md
• certificate lifecycle: docs/certificate-lifecycle.md
• testing and CI: docs/testing-and-ci.md
• live execution tracker: plan.md

---

Open Source

Community and governance files:

• CONTRIBUTING.md
• CODE_OF_CONDUCT.md
• SECURITY.md
• SUPPORT.md
• GOVERNANCE.md
• MAINTAINERS.md
• CHANGELOG.md
• .github/ISSUE_TEMPLATE/
• .github/PULL_REQUEST_TEMPLATE.md
• .github/dependabot.yml

---

Maintainer Links

• Owner profile: https://github.com/xgauravyaduvanshii
• Repository: https://github.com/xgauravyaduvanshii/flyingdarkdevtunnel

---

License

Licensed under the GNU Affero General Public License v3.0.
See LICENSE for full text.