@kortix/agent-tunnel 0.1.0

package/src/server/routes.ts

@@ -0,0 +1,61 @@
+import { Hono } from 'hono';
+import type { TunnelRelay } from './relay';
+import { TunnelRelayError } from './relay';
+import { TunnelErrorCode } from '../shared/types';
+
+export function createTunnelRouter(relay: TunnelRelay): Hono {
+  const router = new Hono();
+
+  router.get('/connections', (c) => {
+    const agents = relay.getConnectedAgents();
+    const list = Array.from(agents.values()).map((a) => ({
+      tunnelId: a.tunnelId,
+      connectedAt: a.connectedAt,
+      metadata: a.metadata,
+    }));
+    return c.json({ connections: list, total: list.length });
+  });
+
+  router.get('/connections/:id', (c) => {
+    const id = c.req.param('id');
+    const agents = relay.getConnectedAgents();
+    const agent = agents.get(id);
+    if (!agent) {
+      return c.json({ error: 'Agent not connected' }, 404);
+    }
+    return c.json({
+      tunnelId: agent.tunnelId,
+      connectedAt: agent.connectedAt,
+      metadata: agent.metadata,
+      connected: true,
+    });
+  });
+
+  router.post('/rpc/:tunnelId', async (c) => {
+    const tunnelId = c.req.param('tunnelId');
+    const body = await c.req.json();
+    const { method, params = {}, timeoutMs } = body;
+
+    if (!method || typeof method !== 'string') {
+      return c.json({ error: 'method is required' }, 400);
+    }
+
+    try {
+      const result = await relay.relayRPC(tunnelId, method, params, {
+        timeoutMs: timeoutMs ?? undefined,
+      });
+      return c.json({ result });
+    } catch (err) {
+      const errorMessage = err instanceof Error ? err.message : String(err);
+      const errorCode = err instanceof TunnelRelayError ? err.code : TunnelErrorCode.LOCAL_ERROR;
+
+      const httpStatus = errorCode === TunnelErrorCode.NOT_CONNECTED ? 502
+        : errorCode === TunnelErrorCode.TIMEOUT ? 504
+        : 500;
+
+      return c.json({ error: errorMessage, code: errorCode }, httpStatus);
+    }
+  });
+
+  return router;
+}

package/src/server/server.ts

@@ -0,0 +1,114 @@
+/**
+ * Standalone tunnel server — one function call to get a working relay.
+ *
+ * Usage:
+ *   import { startTunnelServer } from 'agent-tunnel';
+ *   const server = startTunnelServer({ port: 8080 });
+ *
+ * That's it. Agents connect via: ws://localhost:8080/ws?token=xxx&tunnelId=yyy
+ * Your app calls relay.relayRPC(tunnelId, method, params) to reach the agent.
+ */
+
+import { Hono } from 'hono';
+import { TunnelRelay } from './relay';
+import { HeartbeatManager } from './heartbeat';
+import { createTunnelRouter } from './routes';
+import { createWsHandlers } from './ws-handler';
+import { deriveSigningKey } from '../shared/crypto';
+import type { TunnelServerConfig } from '../shared/types';
+
+export interface TunnelServer {
+  /** Hono app — mount additional routes if needed. */
+  app: Hono;
+  /** The relay instance — call relayRPC() to reach connected agents. */
+  relay: TunnelRelay;
+  heartbeat: HeartbeatManager;
+  wsHandlers: ReturnType<typeof createWsHandlers>;
+  /** Stop the server, heartbeat, and close all connections. */
+  stop: () => void;
+}
+
+/**
+ * Start a tunnel relay server. Handles everything:
+ * - HTTP routes for connections list + RPC
+ * - WebSocket upgrades on /ws for agent connections
+ * - Heartbeat ping/pong
+ * - HMAC signing key derivation from tokens
+ *
+ * Requires Bun runtime for WebSocket server support.
+ */
+export function startTunnelServer(config?: TunnelServerConfig): TunnelServer {
+  const port = config?.port ?? parseInt(process.env.PORT || '8080', 10);
+
+  const relay = new TunnelRelay(config?.relay);
+  const heartbeat = new HeartbeatManager(relay, config?.heartbeat);
+  const wsHandlers = createWsHandlers(relay, { heartbeat });
+
+  const app = new Hono();
+
+  // Mount tunnel routes (GET /connections, POST /rpc/:tunnelId, etc.)
+  const tunnelRouter = createTunnelRouter(relay);
+  app.route('/', tunnelRouter);
+
+  // Health check
+  app.get('/health', (c) => c.json({ status: 'ok', connections: relay.getConnectedCount() }));
+
+  // Start heartbeat
+  heartbeat.start();
+
+  // Start Bun server with WS support
+  const bunServer = Bun.serve({
+    port,
+    fetch(req, server) {
+      const url = new URL(req.url);
+
+      // WS upgrade on /ws
+      if (url.pathname === '/ws') {
+        const token = url.searchParams.get('token');
+        const tunnelId = url.searchParams.get('tunnelId');
+
+        if (!token || !tunnelId) {
+          return new Response(JSON.stringify({ error: 'Missing token or tunnelId' }), {
+            status: 400,
+            headers: { 'Content-Type': 'application/json' },
+          });
+        }
+
+        const signingKey = deriveSigningKey(token);
+
+        const success = server.upgrade(req, {
+          data: { tunnelId, signingKey } as any,
+        });
+        if (success) return undefined;
+
+        return new Response('WebSocket upgrade failed', { status: 500 });
+      }
+
+      // All other requests → Hono
+      return app.fetch(req);
+    },
+
+    websocket: {
+      idleTimeout: 0,
+      open(ws: any) {
+        wsHandlers.onOpen(ws.data.tunnelId, ws, ws.data.signingKey);
+      },
+      message(ws: any, message: string | Buffer) {
+        wsHandlers.onMessage(ws.data.tunnelId, message);
+      },
+      close(ws: any) {
+        wsHandlers.onClose(ws.data.tunnelId);
+      },
+    },
+  });
+
+  console.log(`[agent-tunnel] Server listening on port ${port}`);
+
+  const stop = () => {
+    heartbeat.stop();
+    relay.shutdown();
+    bunServer.stop();
+  };
+
+  return { app, relay, heartbeat, wsHandlers, stop };
+}

package/src/server/ws-handler.ts

@@ -0,0 +1,54 @@
+import type { TunnelRelay } from './relay';
+import type { HeartbeatManager } from './heartbeat';
+
+export interface WsHandlerOptions {
+  heartbeat?: HeartbeatManager;
+  maxMessageSize?: number;
+}
+
+export interface WsHandlers {
+  onOpen(tunnelId: string, ws: WebSocket, signingKey: string, metadata?: Record<string, unknown>): void;
+  onMessage(tunnelId: string, message: string | Buffer): void;
+  onClose(tunnelId: string): void;
+}
+
+export function createWsHandlers(relay: TunnelRelay, opts?: WsHandlerOptions): WsHandlers {
+  const maxMessageSize = opts?.maxMessageSize ?? 5 * 1024 * 1024;
+  const heartbeat = opts?.heartbeat;
+
+  return {
+    onOpen(tunnelId: string, ws: WebSocket, signingKey: string, metadata?: Record<string, unknown>) {
+      relay.registerAgent(tunnelId, ws, signingKey, metadata);
+      if (heartbeat) {
+        heartbeat.register(tunnelId);
+      }
+    },
+
+    onMessage(tunnelId: string, message: string | Buffer) {
+      const msgSize = typeof message === 'string' ? message.length : (message as Buffer).byteLength;
+      if (msgSize > maxMessageSize) {
+        console.warn(`[tunnel-ws] Oversized message from ${tunnelId}: ${msgSize} bytes (limit: ${maxMessageSize})`);
+        return;
+      }
+
+      try {
+        const parsed = JSON.parse(typeof message === 'string' ? message : message.toString('utf-8'));
+        if (parsed.method === 'tunnel.pong') {
+          if (heartbeat) {
+            heartbeat.recordPong(tunnelId);
+          }
+        }
+      } catch {
+      }
+
+      relay.handleAgentMessage(tunnelId, message);
+    },
+
+    onClose(tunnelId: string) {
+      relay.unregisterAgent(tunnelId);
+      if (heartbeat) {
+        heartbeat.unregister(tunnelId);
+      }
+    },
+  };
+}

package/src/shared/crypto.ts

@@ -0,0 +1,58 @@
+import { createHash, createHmac, timingSafeEqual, randomBytes } from 'crypto';
+
+const SIGNING_KEY_CONTEXT = 'kortix-tunnel-signing-v1';
+const CHARS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+
+function randomAlphanumeric(length: number): string {
+  const bytes = randomBytes(length);
+  let result = '';
+  for (let i = 0; i < length; i++) {
+    result += CHARS[bytes[i]! % CHARS.length];
+  }
+  return result;
+}
+
+export function deriveSigningKey(token: string): string {
+  return createHmac('sha256', SIGNING_KEY_CONTEXT)
+    .update(token)
+    .digest('hex');
+}
+
+export function signMessage(signingKey: string, payload: string, nonce: number): string {
+  return createHmac('sha256', signingKey)
+    .update(`${nonce}:${payload}`)
+    .digest('hex');
+}
+
+export function verifyMessageSignature(
+  signingKey: string,
+  payload: string,
+  nonce: number,
+  signature: string,
+): boolean {
+  try {
+    const expected = signMessage(signingKey, payload, nonce);
+    const sigBuffer = Buffer.from(signature, 'hex');
+    const expectedBuffer = Buffer.from(expected, 'hex');
+    if (sigBuffer.length !== expectedBuffer.length) return false;
+    return timingSafeEqual(sigBuffer, expectedBuffer);
+  } catch {
+    return false;
+  }
+}
+
+export function generateToken(prefix = 'tnl_'): string {
+  return `${prefix}${randomAlphanumeric(32)}`;
+}
+
+export function hashToken(token: string, secret: string): string {
+  return createHmac('sha256', secret)
+    .update(token)
+    .digest('hex');
+}
+
+export function timingSafeStringEqual(a: string, b: string): boolean {
+  const hashA = createHash('sha256').update(a).digest();
+  const hashB = createHash('sha256').update(b).digest();
+  return timingSafeEqual(hashA, hashB);
+}

package/src/shared/index.ts

@@ -0,0 +1,33 @@
+export {
+  deriveSigningKey,
+  signMessage,
+  verifyMessageSignature,
+  generateToken,
+  hashToken,
+  timingSafeStringEqual,
+} from './crypto';
+
+export type {
+  JsonRpcRequest,
+  JsonRpcSuccessResponse,
+  JsonRpcErrorResponse,
+  JsonRpcError,
+  JsonRpcResponse,
+  JsonRpcNotification,
+  JsonRpcMessage,
+  SignedJsonRpcRequest,
+  SignedJsonRpcNotification,
+  PendingRPC,
+  TunnelRpcParams,
+  RelayRpcOptions,
+  AgentInfo,
+  TunnelRelayEvents,
+  TunnelRelayConfig,
+  HeartbeatConfig,
+  TunnelServerConfig,
+  TunnelCapability,
+  TunnelMethod,
+  TunnelErrorCodeValue,
+} from './types';
+
+export { TunnelErrorCode, TunnelMethods } from './types';

package/src/shared/types.ts

@@ -0,0 +1,164 @@
+export interface JsonRpcRequest {
+  jsonrpc: '2.0';
+  id: string;
+  method: string;
+  params?: Record<string, unknown>;
+}
+
+export interface JsonRpcSuccessResponse {
+  jsonrpc: '2.0';
+  id: string;
+  result: unknown;
+}
+
+export interface JsonRpcErrorResponse {
+  jsonrpc: '2.0';
+  id: string;
+  error: JsonRpcError;
+}
+
+export interface JsonRpcError {
+  code: number;
+  message: string;
+  data?: unknown;
+}
+
+export type JsonRpcResponse = JsonRpcSuccessResponse | JsonRpcErrorResponse;
+
+export interface JsonRpcNotification {
+  jsonrpc: '2.0';
+  method: string;
+  params?: Record<string, unknown>;
+}
+
+export type JsonRpcMessage = JsonRpcRequest | JsonRpcResponse | JsonRpcNotification;
+
+export const TunnelErrorCode = {
+  PERMISSION_DENIED: -32000,
+  CAPABILITY_NOT_REGISTERED: -32001,
+  TIMEOUT: -32002,
+  LOCAL_ERROR: -32003,
+  NOT_CONNECTED: -32004,
+  EXPIRED: -32005,
+  RATE_LIMITED: -32006,
+} as const;
+
+export type TunnelErrorCodeValue = (typeof TunnelErrorCode)[keyof typeof TunnelErrorCode];
+
+export type TunnelCapability =
+  | 'filesystem'
+  | 'shell'
+  | 'network'
+  | 'apps'
+  | 'hardware'
+  | 'desktop'
+  | 'gpu';
+
+export const TunnelMethods = {
+  'fs.read': 'filesystem',
+  'fs.write': 'filesystem',
+  'fs.list': 'filesystem',
+  'fs.stat': 'filesystem',
+  'fs.delete': 'filesystem',
+  'shell.exec': 'shell',
+  'desktop.screenshot': 'desktop',
+  'desktop.mouse.click': 'desktop',
+  'desktop.mouse.move': 'desktop',
+  'desktop.mouse.drag': 'desktop',
+  'desktop.mouse.scroll': 'desktop',
+  'desktop.mouse.position': 'desktop',
+  'desktop.keyboard.type': 'desktop',
+  'desktop.keyboard.key': 'desktop',
+  'desktop.window.list': 'desktop',
+  'desktop.window.focus': 'desktop',
+  'desktop.window.resize': 'desktop',
+  'desktop.window.close': 'desktop',
+  'desktop.window.minimize': 'desktop',
+  'desktop.app.launch': 'desktop',
+  'desktop.app.quit': 'desktop',
+  'desktop.app.list': 'desktop',
+  'desktop.clipboard.read': 'desktop',
+  'desktop.clipboard.write': 'desktop',
+  'desktop.screen.info': 'desktop',
+  'desktop.cursor.image': 'desktop',
+  'desktop.ax.tree': 'desktop',
+  'desktop.ax.action': 'desktop',
+  'desktop.ax.set_value': 'desktop',
+  'desktop.ax.focus': 'desktop',
+  'desktop.ax.search': 'desktop',
+  'net.request': 'network',
+  'net.port_forward.start': 'network',
+  'net.port_forward.stop': 'network',
+  'tunnel.ping': null,
+  'tunnel.pong': null,
+  'tunnel.permission.revoked': null,
+  'tunnel.permissions.sync': null,
+  'tunnel.token.rotated': null,
+} as const;
+
+export type TunnelMethod = keyof typeof TunnelMethods;
+
+export interface PendingRPC {
+  resolve: (value: unknown) => void;
+  reject: (error: Error) => void;
+  timer: ReturnType<typeof setTimeout>;
+  method: string;
+  tunnelId: string;
+  startedAt: number;
+}
+
+export interface SignedJsonRpcRequest extends JsonRpcRequest {
+  _sig: string;
+  _nonce: number;
+}
+
+export interface SignedJsonRpcNotification extends JsonRpcNotification {
+  _sig: string;
+  _nonce: number;
+}
+
+export interface TunnelRpcParams {
+  capability: TunnelCapability;
+  operation: string;
+  args: Record<string, unknown>;
+  permissionId?: string;
+}
+
+export interface RelayRpcOptions {
+  timeoutMs?: number;
+}
+
+export interface AgentInfo {
+  tunnelId: string;
+  signingKey: string;
+  connectedAt: number;
+  metadata?: Record<string, unknown>;
+}
+
+export interface TunnelRelayEvents {
+  'agent:connect': { tunnelId: string; metadata?: Record<string, unknown> };
+  'agent:disconnect': { tunnelId: string };
+  'agent:timeout': { tunnelId: string };
+  'rpc:request': { tunnelId: string; method: string; requestId: string };
+  'rpc:response': { tunnelId: string; method: string; requestId: string; durationMs: number };
+  'rpc:error': { tunnelId: string; method: string; requestId: string; error: Error };
+  'connection:replaced': { tunnelId: string };
+  'message:pong': { tunnelId: string; params?: Record<string, unknown> };
+  'message:raw': { tunnelId: string; message: unknown };
+}
+
+export interface TunnelRelayConfig {
+  rpcTimeoutMs?: number;
+  maxWsMessageSize?: number;
+}
+
+export interface HeartbeatConfig {
+  intervalMs?: number;
+  maxMissed?: number;
+}
+
+export interface TunnelServerConfig {
+  port?: number;
+  relay?: TunnelRelayConfig;
+  heartbeat?: HeartbeatConfig;
+}