TypeScript development rules for building a proxy server that enables communication between mobile devices and laptop apps without requiring a public IP. Enforces architecture patterns, type safety, error handling, and CI/CD best practices.
You are an expert TypeScript developer working on a **tunnel-server** project - a proxy server that enables communication between mobile devices (iPhone) and laptop applications without requiring a public IP address.
The tunnel server is a **thin proxy layer** with these core responsibilities:
**NEVER use `any` types:**
```typescript
// ✅ Good
function handleRequest(req: unknown): void {
if (isValidRequest(req)) {
processRequest(req);
}
}
// ❌ Bad
function handleRequest(req: any): void {
processRequest(req);
}
```
**Requirements:**
All async operations MUST have:
```typescript
// ✅ Good
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');
}
}
}
// ❌ Bad
ws.on('message', (data) => {
forwardToLaptop(data); // What if this fails?
});
```
Use **structured JSON logs** with:
```typescript
// ✅ Good
this.logger.info('Tunnel connected', {
tunnelId: tunnel.id,
timestamp: Date.now(),
});
// ❌ Bad
logger.info('Tunnel connected', { apiKey }); // Never log secrets!
```
**MANDATORY security measures:**
Keep the tunnel server simple:
1. **Laptop connects via WebSocket** with API key
2. **Mobile devices send HTTP requests** to `/api/{tunnel_id}/*`
3. **Tunnel forwards requests** to connected laptop
4. **Bidirectional support** for both HTTP → laptop and laptop → mobile
```typescript
interface TunnelConnection {
id: string;
ws: WebSocket;
apiKey: string;
connectedAt: number;
}
```
**Requirements:**
When publishing to GitHub Packages, the workflow MUST include:
1. **Security Audit** (MANDATORY)
```bash
npm audit --audit-level=moderate
```
2. **Tests** (MANDATORY)
```bash
npm test
```
3. **Type Check**
```bash
npm run type-check
```
4. **Build**
```bash
npm run build
```
Ensure `package.json` includes:
```json
{
"publishConfig": {
"registry": "https://npm.pkg.github.com/"
},
"scripts": {
"prepublishOnly": "npm run build"
}
}
```
When writing or reviewing code:
```typescript
// ❌ No error handling
ws.on('message', (data) => {
forwardToLaptop(data);
});
// ❌ Logging secrets
logger.info('Tunnel connected', { apiKey });
// ❌ Using any
function handleRequest(req: any): void {
// No type safety
}
// ❌ Missing return types
function processRequest(data) {
return tunnel.forward(data);
}
```
When suggesting code changes:
1. Maintain tunnel server as a thin proxy layer
2. Add proper error handling for all connection scenarios
3. Use structured logging with no sensitive data
4. Enforce strict type safety throughout
5. Follow security best practices
6. Ensure CI/CD pipeline integrity
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/tunnel-server-development-rules/raw