Tunnel Server - TypeScript Development

You are working on the **tunnel-server** - a proxy server that enables communication between mobile devices (iPhone) and the laptop app without requiring a public IP address.

Project Architecture

The tunnel server is a **thin proxy layer** with the following responsibilities:

TypeScript Architecture Rules

All code MUST follow these principles:

1. Separation of Concerns

2. Type Safety

Example:

```typescript

// ✅ Good

function handleRequest(req: TunnelRequest): Promise<TunnelResponse> {

// Implementation

}

// ❌ Bad

function handleRequest(req: any) {

// Implementation

}

```

3. Error Handling

All errors must be handled gracefully:

Example:

```typescript

class TunnelServer {

async handleWebSocketConnection(ws: WebSocket, apiKey: string): Promise<void> {

try {

const tunnel = await this.validateTunnel(apiKey);

this.logger.info('Tunnel connected', {

tunnelId: tunnel.id,

timestamp: Date.now(),

});

ws.on('close', () => {

this.logger.info('Tunnel disconnected', { tunnelId: tunnel.id });

this.removeTunnel(tunnel.id);

});

this.registerTunnel(tunnel.id, ws);

} catch (error) {

this.logger.error('Tunnel connection failed', { error, apiKey: '***' });

ws.close(1008, 'Authentication failed');

}

}

}

```

4. Logging

Use structured logging throughout:

5. Code Organization

6. Security

Tunnel Protocol

Connection Flow

1. **WebSocket connection**: Laptop connects via WebSocket with API key

2. **HTTP proxy**: Mobile devices send HTTP requests, tunnel forwards to laptop

3. **Request routing**: Route `/api/{tunnel_id}/*` to connected laptop

4. **Bidirectional**: Support both HTTP → laptop and laptop → mobile

Connection Management

Anti-Patterns to Avoid

```typescript

// ❌ No error handling

ws.on('message', (data) => {

forwardToLaptop(data); // What if this fails?

});

// ❌ Logging secrets

logger.info('Tunnel connected', { apiKey }); // ❌ Never do this

// ❌ Using any

function handleRequest(req: any): void {

// No type safety

}

```

CI/CD Requirements

This package is published to GitHub Packages and MUST have:

GitHub Actions Workflow

Create `.github/workflows/publish-tunnel-server.yml`:

1. **Security audit**: `npm audit --audit-level=moderate` (MANDATORY before build)

2. **Tests**: `npm test` (MANDATORY, all must pass before build)

3. **Type check**: `npm run type-check`

4. **Build**: `npm run build`

5. **Publish**: Publish to GitHub Packages

Package Configuration

Ensure `package.json` includes:

Development Workflow

When making changes:

1. **Review architecture**: Keep tunnel server as a thin proxy

2. **Handle errors**: Add proper error handling for connection issues

3. **Add logging**: Log important events (connections, disconnections, errors)

4. **Maintain type safety**: No `any` types, use explicit return types

5. **Test**: Test WebSocket connections and HTTP proxying

6. **Security**: Validate inputs, never log secrets

7. **CI/CD**: Ensure GitHub Actions workflow includes audit + tests before publishing

Summary

The tunnel server must remain a simple, secure, and reliable proxy layer. Focus on connection management, error handling, structured logging, and type safety. Never add business logic - keep it in the laptop app.