@kortix/agent-tunnel 0.1.2 → 0.1.4

package/dist/agent/index.d.ts

@@ -0,0 +1,140 @@
+interface TunnelConfig {
+    token: string;
+    tunnelId: string;
+    apiUrl: string;
+    wsPath: string;
+    maxFileSize: number;
+    allowedPaths: string[];
+    allowedCommands: string[];
+    blockedCommands: string[];
+    blockedPaths: string[];
+    workingDir: string;
+    shellTimeout: number;
+    shellMaxTimeout: number;
+    shellMaxOutputSize: number;
+    shellEnvPassthrough: string[];
+}
+declare function loadConfig(overrides?: Partial<TunnelConfig>): TunnelConfig;
+
+/**
+ * Capability Registry — extensible registry for tunnel capabilities.
+ *
+ * Each capability (filesystem, shell, network, etc.) registers its
+ * RPC method handlers here. The TunnelAgent dispatches incoming
+ * JSON-RPC requests to the matching handler.
+ */
+type RpcHandler = (params: Record<string, unknown>) => Promise<unknown>;
+interface Capability {
+    name: string;
+    methods: Map<string, RpcHandler>;
+}
+declare class CapabilityRegistry {
+    private capabilities;
+    register(capability: Capability): void;
+    unregister(name: string): void;
+    getHandler(method: string): RpcHandler | null;
+    getCapabilityNames(): string[];
+    has(name: string): boolean;
+}
+
+declare class TunnelAgent {
+    private ws;
+    private registry;
+    private permissionGuard;
+    private config;
+    private reconnectAttempts;
+    private maxReconnectDelay;
+    private baseReconnectDelay;
+    private reconnectTimer;
+    private isShuttingDown;
+    private uptime;
+    private uptimeInterval;
+    private signingKey;
+    private lastNonce;
+    private responseNonce;
+    constructor(config: TunnelConfig, registry: CapabilityRegistry);
+    connect(): void;
+    disconnect(): void;
+    isConnected(): boolean;
+    private setupWsHandlers;
+    private handleMessage;
+    /**
+     * Verify HMAC signature on incoming messages (excluding pings).
+     */
+    private verifyIncomingSignature;
+    private handleRpcRequest;
+    /** Send HMAC-signed RPC result. */
+    private sendSignedResult;
+    /** Send HMAC-signed RPC error. */
+    private sendSignedError;
+    private sendSigned;
+    private send;
+    private sendPong;
+    private scheduleReconnect;
+    private buildWsUrl;
+}
+
+/**
+ * Filesystem Capability — handles fs.read, fs.write, fs.list, fs.stat, fs.delete.
+ *
+ * All operations go through local-side path validation (defense in depth)
+ * even though the server already validates permissions.
+ */
+
+declare function createFilesystemCapability(config: TunnelConfig): Capability;
+
+/**
+ * Shell Capability — handles shell.exec for running commands on the local machine.
+ *
+ * Security:
+ *   - Commands are executed as array args (no shell interpolation)
+ *   - First arg (executable) is validated against allowedCommands / blockedCommands
+ *   - Working directory is validated against allowedPaths / blockedPaths
+ *   - Timeout enforcement
+ */
+
+declare function createShellCapability(config: TunnelConfig): Capability;
+
+declare function createDesktopCapability(): Capability;
+
+/**
+ * Permission Guard — local-side permission enforcement (defense in depth).
+ *
+ * Even though the server validates permissions before relaying RPCs,
+ * the local agent also checks permissions as a second layer of defense.
+ * This prevents a compromised server from bypassing permission controls.
+ *
+ * After the initial permission sync, unknown permissionIds are denied.
+ * Before sync, unknown IDs are also denied (fail-closed).
+ */
+interface LocalPermission {
+    permissionId: string;
+    capability: string;
+    scope: Record<string, unknown>;
+    expiresAt?: string;
+}
+declare class PermissionGuard {
+    private permissions;
+    private hasSynced;
+    /** Bulk-load permissions from server sync notification. */
+    syncPermissions(permissions: LocalPermission[]): void;
+    addPermission(permission: LocalPermission): void;
+    revokePermission(permissionId: string): void;
+    checkPermission(permissionId: string | undefined): boolean;
+    clear(): void;
+}
+
+declare function validateCommand(command: string, allowedCommands: string[], blockedCommands: string[]): void;
+
+/**
+ * Path Validator — defense-in-depth path traversal prevention.
+ *
+ * Validates that requested paths:
+ *   1. Are absolute
+ *   2. Resolve to an absolute path (follows symlinks)
+ *   3. Fall within allowed directories
+ *   4. Don't hit blocked paths (configurable)
+ */
+declare function validatePath(path: string, allowedPaths: string[], blockedPaths?: string[]): void;
+
+export { type Capability, CapabilityRegistry, type LocalPermission, PermissionGuard, type RpcHandler, TunnelAgent, type TunnelConfig, createDesktopCapability, createFilesystemCapability, createShellCapability, loadConfig, validateCommand, validatePath };

package/dist/agent/index.js

@@ -0,0 +1,21 @@
+import { TunnelAgent } from "./agent";
+import { loadConfig } from "./config";
+import { CapabilityRegistry } from "./capabilities/index";
+import { createFilesystemCapability } from "./capabilities/filesystem";
+import { createShellCapability } from "./capabilities/shell";
+import { createDesktopCapability } from "./capabilities/desktop";
+import { PermissionGuard } from "./security/permission-guard";
+import { validateCommand } from "./security/command-validator";
+import { validatePath } from "./security/path-validator";
+export {
+  CapabilityRegistry,
+  PermissionGuard,
+  TunnelAgent,
+  createDesktopCapability,
+  createFilesystemCapability,
+  createShellCapability,
+  loadConfig,
+  validateCommand,
+  validatePath
+};
+//# sourceMappingURL=index.js.map

package/dist/agent/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/agent/index.ts"],"sourcesContent":["export { TunnelAgent } from './agent';\nexport { loadConfig, type TunnelConfig } from './config';\nexport { CapabilityRegistry } from './capabilities/index';\nexport type { Capability, RpcHandler } from './capabilities/index';\nexport { createFilesystemCapability } from './capabilities/filesystem';\nexport { createShellCapability } from './capabilities/shell';\nexport { createDesktopCapability } from './capabilities/desktop';\nexport { PermissionGuard } from './security/permission-guard';\nexport type { LocalPermission } from './security/permission-guard';\nexport { validateCommand } from './security/command-validator';\nexport { validatePath } from './security/path-validator';\n"],"mappings":"AAAA,SAAS,mBAAmB;AAC5B,SAAS,kBAAqC;AAC9C,SAAS,0BAA0B;AAEnC,SAAS,kCAAkC;AAC3C,SAAS,6BAA6B;AACtC,SAAS,+BAA+B;AACxC,SAAS,uBAAuB;AAEhC,SAAS,uBAAuB;AAChC,SAAS,oBAAoB;","names":[]}