Sentry Tunnel for Bun

A lightweight and fast tunnel implementation using Bun and Elysia. This tunnel acts as a proxy between your client applications and Sentry-compatible servers, helping to bypass ad-blockers that might block direct connections. Works with any service that uses the Sentry envelope protocol, including Sentry and GlitchTip.

What is a Sentry Tunnel?

A tunnel is an HTTP endpoint that acts as a proxy between Sentry and your application. Because you control this server, there is no risk of any requests sent to it being blocked. When the endpoint lives under the same origin as your application, the browser will not treat any requests to the endpoint as third-party requests. As a result, these requests will have different security measures applied which, by default, don't trigger ad-blockers.

See the Sentry docs for more details.

Features

• Fast and lightweight implementation using Bun and Elysia
• Works with any Sentry-compatible host (Sentry, GlitchTip, etc.)
• Project allowlist persisted in allowlist.json, managed at runtime via admin API
• CLI tool (stun) for managing the allowlist without restarting the server
• Admin API secured with Bearer token authentication
• Easy to deploy and maintain
• Minimal dependencies
• Detailed logging in development mode with timestamps and request IDs
• HTTPS support when SSL certificates are provided
• Built-in CORS support for handling preflight requests

Prerequisites

• Bun 1.2.2 or higher

Configuration

The following environment variables can be configured:

• ADMIN_API_KEY: API key for admin endpoints (required)
• ALLOWED_PROJECT_IDS: Comma-separated list of project IDs to seed the allowlist on first run (optional, ignored once allowlist.json exists)
• TUNNEL_URL: Default URL for the CLI tool (default: http://localhost:3010)
• PORT: Port to listen on (default: 3010)
• ENV: Environment mode (development, production, or test, default: development)
• SSL_CERT_PATH: Path to SSL certificate file (optional, enables HTTPS when provided)
• SSL_KEY_PATH: Path to SSL key file (optional, enables HTTPS when provided)

Usage

Starting the Server

bun start

The server will start on the configured port (default: 3010) using either HTTP or HTTPS based on the availability of SSL certificates.

Development Mode Logging

When running in development mode, the server outputs detailed logs about each request and response, which is helpful for debugging. Each log entry includes:

• ISO and local timestamps for precise timing information
• Unique request ID for tracking a request through its lifecycle
• Detailed information about the request processing stages

Example log output:

2023-07-15T12:34:56.789Z [12:34:56 PM] [DEV] [a1b2c3d4] Received request to tunnel endpoint
2023-07-15T12:34:56.790Z [12:34:56 PM] [DEV] [a1b2c3d4] Envelope has 2 pieces
2023-07-15T12:34:56.791Z [12:34:56 PM] [DEV] [a1b2c3d4] Forwarding to Sentry URL: https://o0.ingest.sentry.io/api/12345/envelope/?sentry_key=abcdef
2023-07-15T12:34:56.900Z [12:34:56 PM] [DEV] [a1b2c3d4] Received response from Sentry with status: 200 (took 109ms)
2023-07-15T12:34:56.901Z [12:34:56 PM] [DEV] [a1b2c3d4] Request completed successfully

Client-Side Configuration

In your client application, configure Sentry to use the tunnel:

import * as Sentry from '@sentry/browser';

Sentry.init({
  dsn: 'https://[email protected]/your-project-id',
  tunnel: 'https://your-server.com/tunnel', // URL to your tunnel endpoint
  // other Sentry configuration options...
});

CLI

The stun CLI manages the project allowlist via the admin API. Secrets are never accepted via argv flags. Configure adminApiKey via env (ADMIN_API_KEY) or stdin into config.

# Run without install (from npm)
bunx @vforsh/stun list

# Install globally from local source
bun link

# Configure endpoint and key (XDG config)
stun cfg set endpoint https://tunnel.example.com
printf "%s" "$ADMIN_API_KEY" | stun cfg set adminApiKey -

# Readiness checks
stun doctor

# List allowed projects
stun list

# Add a project
stun add 123 --label "My Web App"

# Remove a project
stun remove 123

# Override endpoint for one command
stun list --endpoint https://tunnel.example.com

You can also run it without installing globally:

bun run cmd list
bun run cmd add 123 --label "My Web App"
bun run cmd remove 123

Publish to npm

This repo publishes as @vforsh/stun (scoped public package).

npm whoami
npm publish --access public

After publishing:

bunx @vforsh/stun list

Note: bunx stun resolves the unscoped stun package on npm, which is currently owned by another project.

Domain blocking

Block envelopes from specific domains on a per-project basis. Blocking example.com also blocks subdomains like sub.example.com.

stun domain list 123
stun domain block 123 poki.com
stun domain unblock 123 poki.com

Admin API

All admin endpoints require an Authorization: Bearer <ADMIN_API_KEY> header.

• GET /admin/projects — list allowed projects
• POST /admin/projects — add a project ({ "projectId": "123", "label": "My App" })
• DELETE /admin/projects/:id — remove a project
• POST /admin/projects/:id/blocked-domains — block a domain ({ "domain": "example.com" })
• DELETE /admin/projects/:id/blocked-domains/:domain — unblock a domain

How It Works

1. Your client application sends Sentry-compatible envelopes to your tunnel endpoint instead of directly to the error tracking server.
2. The tunnel server receives the envelopes, validates them, and forwards them to the actual server (Sentry, GlitchTip, or any other compatible host).
3. The tunnel server returns the response back to your client application.

Security Considerations

• The tunnel server should be properly secured, as it acts as a proxy for your Sentry events.
• Use HTTPS in production environments by providing valid SSL certificates.
• The project allowlist is always enforced — an empty allowlist rejects all tunnel requests.
• Use the admin API or CLI to manage allowed projects at runtime.
• In production, consider placing the tunnel behind a reverse proxy (like Nginx or Cloudflare) for additional security.

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.