helmpilot 0.4.2

package/__tests__/setup-adapter.test.ts

@@ -0,0 +1,138 @@
+import { describe, expect, it } from 'vitest';
+import { createSetupAdapter } from '../adapters.js';
+
+describe('createSetupAdapter', () => {
+  const setup = createSetupAdapter();
+  const emptyCfg = {};
+
+  describe('applyAccountConfig', () => {
+    it('maps --url to relayUrl', () => {
+      const result = setup.applyAccountConfig({
+        cfg: emptyCfg,
+        accountId: 'default',
+        input: { url: 'wss://relay.example.com' },
+      });
+      expect((result as any).channels.helmpilot.relayUrl).toBe('wss://relay.example.com');
+      expect((result as any).channels.helmpilot.enabled).toBe(true);
+    });
+
+    it('maps --token to channelKey', () => {
+      const result = setup.applyAccountConfig({
+        cfg: emptyCfg,
+        accountId: 'default',
+        input: { token: 'ck_abc123' },
+      });
+      expect((result as any).channels.helmpilot.channelKey).toBe('ck_abc123');
+    });
+
+    it('maps --code to channelId', () => {
+      const result = setup.applyAccountConfig({
+        cfg: emptyCfg,
+        accountId: 'default',
+        input: { code: 'ch_abc123' },
+      });
+      expect((result as any).channels.helmpilot.channelId).toBe('ch_abc123');
+    });
+
+    it('maps all three fields at once', () => {
+      const result = setup.applyAccountConfig({
+        cfg: emptyCfg,
+        accountId: 'default',
+        input: { url: 'wss://relay.example.com', code: 'ch_abc', token: 'ck_xyz' },
+      });
+      const hp = (result as any).channels.helmpilot;
+      expect(hp.relayUrl).toBe('wss://relay.example.com');
+      expect(hp.channelId).toBe('ch_abc');
+      expect(hp.channelKey).toBe('ck_xyz');
+      expect(hp.enabled).toBe(true);
+    });
+
+    it('preserves existing config', () => {
+      const cfg = { channels: { helmpilot: { relayUrl: 'wss://old.example.com' } } };
+      const result = setup.applyAccountConfig({
+        cfg,
+        accountId: 'default',
+        input: { token: 'ck_new' },
+      });
+      const hp = (result as any).channels.helmpilot;
+      expect(hp.relayUrl).toBe('wss://old.example.com');
+      expect(hp.channelKey).toBe('ck_new');
+    });
+
+    it('does not mutate original config', () => {
+      const cfg = { channels: { helmpilot: { relayUrl: 'wss://orig.com' } } };
+      setup.applyAccountConfig({ cfg, accountId: 'default', input: { token: 'ck_x' } });
+      expect((cfg as any).channels.helmpilot.channelKey).toBeUndefined();
+    });
+  });
+
+  describe('validateInput', () => {
+    it('rejects empty input', () => {
+      expect(setup.validateInput({ cfg: emptyCfg, accountId: 'default', input: {} })).toBeTruthy();
+    });
+
+    it('rejects invalid URL protocol', () => {
+      const err = setup.validateInput({
+        cfg: emptyCfg,
+        accountId: 'default',
+        input: { url: 'ftp://relay.example.com' },
+      });
+      expect(err).toContain('protocol');
+    });
+
+    it('rejects malformed URL', () => {
+      const err = setup.validateInput({
+        cfg: emptyCfg,
+        accountId: 'default',
+        input: { url: 'not-a-url' },
+      });
+      expect(err).toContain('Invalid');
+    });
+
+    it('rejects token without ck_ prefix', () => {
+      const err = setup.validateInput({
+        cfg: emptyCfg,
+        accountId: 'default',
+        input: { token: 'bad_token' },
+      });
+      expect(err).toContain('ck_');
+    });
+
+    it('rejects code without ch_ prefix', () => {
+      const err = setup.validateInput({
+        cfg: emptyCfg,
+        accountId: 'default',
+        input: { code: 'bad_channel' },
+      });
+      expect(err).toContain('ch_');
+    });
+
+    it('accepts valid url only', () => {
+      expect(
+        setup.validateInput({ cfg: emptyCfg, accountId: 'default', input: { url: 'wss://r.com' } }),
+      ).toBeNull();
+    });
+
+    it('accepts valid code only', () => {
+      expect(
+        setup.validateInput({ cfg: emptyCfg, accountId: 'default', input: { code: 'ch_abc' } }),
+      ).toBeNull();
+    });
+
+    it('accepts valid token only', () => {
+      expect(
+        setup.validateInput({ cfg: emptyCfg, accountId: 'default', input: { token: 'ck_abc' } }),
+      ).toBeNull();
+    });
+
+    it('accepts all three valid inputs', () => {
+      expect(
+        setup.validateInput({
+          cfg: emptyCfg,
+          accountId: 'default',
+          input: { url: 'wss://r.com', code: 'ch_abc', token: 'ck_xyz' },
+        }),
+      ).toBeNull();
+    });
+  });
+});

package/adapters.ts

@@ -0,0 +1,242 @@
+/**
+ * Helmpilot Channel — Adapters
+ *
+ * Implements: Messaging, Setup, Status, Pairing, Security adapters
+ * for the full ChannelPlugin interface.
+ */
+
+import type { RelayConnectionState } from './relay-client.js';
+import { getRelay } from './relay-registry.js';
+
+// ── Constants ──
+
+const CHANNEL_ID = 'helmpilot';
+const DEFAULT_ACCOUNT_ID = 'default';
+const HELMPILOT_CONFIG_SECTION = 'channels.helmpilot';
+
+// ── Messaging Adapter ──
+
+/**
+ * Helmpilot targets are simple: a single device per channel.
+ * Target format: "helmpilot:default" or just "default".
+ */
+export function createMessagingAdapter() {
+  return {
+    normalizeTarget(raw: string): string | undefined {
+      if (!raw) return undefined;
+      // Strip channel prefix if present
+      const stripped = raw.startsWith('helmpilot:') ? raw.slice(10) : raw;
+      return stripped || undefined;
+    },
+
+    targetResolver: {
+      looksLikeId(raw: string): boolean {
+        // Helmpilot targets are simple identifiers (no complex format)
+        return /^[a-zA-Z0-9_-]+$/.test(raw);
+      },
+      hint: 'Device ID (default: "default")',
+    },
+  };
+}
+
+// ── Setup Adapter ──
+
+/**
+ * CLI configuration wizard for helmpilot-channel.
+ *
+ * Supports input fields:
+ *   - url: Relay URL (e.g. wss://relay.example.com)
+ *   - token: Channel key (ck_xxx...)
+ */
+export function createSetupAdapter() {
+  return {
+    applyAccountConfig(params: {
+      cfg: Record<string, unknown>;
+      accountId: string;
+      input: { url?: string; token?: string; code?: string };
+    }): Record<string, unknown> {
+      const cfg = structuredClone(params.cfg);
+      const channels = (cfg.channels ?? {}) as Record<string, unknown>;
+      const hp = (channels.helmpilot ?? {}) as Record<string, unknown>;
+
+      if (params.input.url) {
+        hp.relayUrl = params.input.url;
+      }
+      if (params.input.code) {
+        hp.channelId = params.input.code;
+      }
+      if (params.input.token) {
+        hp.channelKey = params.input.token;
+      }
+      hp.enabled = true;
+
+      channels.helmpilot = hp;
+      cfg.channels = channels;
+      return cfg;
+    },
+
+    validateInput(params: {
+      cfg: Record<string, unknown>;
+      accountId: string;
+      input: { url?: string; token?: string; code?: string };
+    }): string | null {
+      const { url, token, code } = params.input;
+
+      if (url) {
+        try {
+          const parsed = new URL(url);
+          if (!['ws:', 'wss:', 'http:', 'https:'].includes(parsed.protocol)) {
+            return 'Relay URL must use ws://, wss://, http://, or https:// protocol';
+          }
+        } catch {
+          return 'Invalid Relay URL format';
+        }
+      }
+
+      if (code && !code.startsWith('ch_')) {
+        return 'Channel ID must start with "ch_"';
+      }
+
+      if (token && !token.startsWith('ck_')) {
+        return 'Channel key must start with "ck_"';
+      }
+
+      // Check for required fields (existing config values fill gaps)
+      const channels = (params.cfg?.channels ?? {}) as Record<string, unknown>;
+      const existing = (channels?.helmpilot ?? {}) as Record<string, unknown>;
+      const hasUrl = url || existing.relayUrl;
+      const hasCode = code || existing.channelId;
+      const hasToken = token || typeof existing.channelKey === 'string';
+
+      if (!hasUrl && !hasCode && !hasToken) {
+        return 'Helmpilot requires --url (Relay URL), --code (channel ID), and --token (channel key).\n'
+          + 'Example: openclaw channels add --channel helmpilot --url ws://localhost:4800 --code ch_xxx --token ck_xxx';
+      }
+
+      return null;
+    },
+  };
+}
+
+// ── Status Adapter ──
+
+/**
+ * Connection health and account status reporting.
+ */
+export function createStatusAdapter() {
+  return {
+    defaultRuntime: {
+      accountId: DEFAULT_ACCOUNT_ID,
+      running: false,
+      connected: false,
+      lastConnectedAt: null,
+      lastError: null,
+      lastInboundAt: null,
+      lastOutboundAt: null,
+    },
+
+    buildChannelSummary(params: {
+      snapshot: { configured?: boolean; running?: boolean; connected?: boolean; lastError?: string | null };
+    }) {
+      return {
+        configured: params.snapshot.configured ?? false,
+        running: params.snapshot.running ?? false,
+        connected: params.snapshot.connected ?? false,
+        lastError: params.snapshot.lastError ?? null,
+      };
+    },
+
+    buildAccountSnapshot(params: {
+      account: { accountId: string; config: { enabled?: boolean; relayUrl?: string; channelKey?: string } };
+      cfg: Record<string, unknown>;
+      runtime?: {
+        running?: boolean;
+        connected?: boolean;
+        lastConnectedAt?: number | null;
+        lastError?: string | null;
+        lastInboundAt?: number | null;
+        lastOutboundAt?: number | null;
+      };
+    }) {
+      const { account, runtime } = params;
+      const relay = getRelay(account.accountId);
+      const relayState = relay?.getState() ?? 'disconnected';
+
+      return {
+        accountId: account.accountId,
+        enabled: account.config.enabled !== false,
+        configured: Boolean(account.config.relayUrl && account.config.channelKey),
+        mode: account.config.relayUrl ? 'relay' : 'local',
+        running: runtime?.running ?? false,
+        connected: relayState === 'connected',
+        lastConnectedAt: runtime?.lastConnectedAt ?? null,
+        lastError: runtime?.lastError ?? null,
+        lastInboundAt: runtime?.lastInboundAt ?? null,
+        lastOutboundAt: runtime?.lastOutboundAt ?? null,
+      };
+    },
+
+    probeAccount(params: {
+      account: { accountId: string; config: { relayUrl?: string; channelKey?: string } };
+      timeoutMs: number;
+    }) {
+      const relay = getRelay(params.account.accountId);
+      return Promise.resolve({
+        relayConnected: relay?.getState() === 'connected',
+        relayUrl: params.account.config.relayUrl ?? null,
+        hasChannelKey: Boolean(params.account.config.channelKey),
+      });
+    },
+  };
+}
+
+// ── Pairing Adapter ──
+
+/**
+ * Device pairing adapter.
+ *
+ * Helmpilot uses device keys (dk_xxx) for authentication.
+ * The pairing flow is manual: user creates a channel on the relay,
+ * then enters the device key in the Helmpilot client.
+ */
+export function createPairingAdapter() {
+  return {
+    idLabel: 'Device Key',
+
+    normalizeAllowEntry(entry: string): string {
+      // Device keys start with dk_; normalize by trimming whitespace
+      return entry.trim();
+    },
+  };
+}
+
+// ── Security Adapter ──
+
+/**
+ * DM policy enforcement for Helmpilot connections.
+ *
+ * Since Helmpilot is a 1:1 desktop client (not a group platform), the security
+ * model is simpler: if the device has a valid key, it's authorized.
+ */
+export function createSecurityAdapter() {
+  return {
+    resolveDmPolicy(ctx: {
+      account: { accountId: string; config: { enabled?: boolean; relayUrl?: string; channelKey?: string } };
+      cfg: Record<string, unknown>;
+    }) {
+      const { config } = ctx.account;
+
+      // Not configured or disabled → no policy (deny)
+      if (!config.relayUrl || !config.channelKey || config.enabled === false) {
+        return null;
+      }
+
+      // Configured and enabled → allow (device auth is handled at relay level)
+      return {
+        policy: 'open',
+        allowFromPath: `${HELMPILOT_CONFIG_SECTION}.allowFrom`,
+        approveHint: 'Helmpilot desktop devices authenticate via relay channel keys',
+      };
+    },
+  };
+}

package/bridge.ts

@@ -0,0 +1,220 @@
+/**
+ * LocalBridge — manages the WebSocket connection between the Relay tunnel
+ * and the local OpenClaw Gateway instance.
+ *
+ * The bridge is a transparent tunnel: it forwards raw WS frames between
+ * the RelayClient (remote device) and the local gateway, without parsing
+ * or interpreting the OpenClaw protocol messages.
+ *
+ * For the initial `connect` RPC, the bridge re-signs the device identity
+ * with the gateway token (which the remote device doesn't know), so the
+ * gateway's token auth AND device signature verification both pass.
+ *
+ * Includes WS-level ping/pong heartbeat to detect dead connections.
+ */
+
+import crypto from 'node:crypto';
+import { WebSocket as WsWebSocket } from 'ws';
+
+/** Ping interval — shorter than relay's 25s to detect failures early */
+const PING_INTERVAL_MS = 20_000;
+/** If no pong received within this duration, close the connection */
+const PONG_TIMEOUT_MS = 10_000;
+
+/** Encode a Buffer to base64url (no padding) */
+function base64UrlEncode(buf: Buffer): string {
+  return buf.toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/g, '');
+}
+
+/** SPKI DER prefix for Ed25519 public keys */
+const ED25519_SPKI_PREFIX = Buffer.from('302a300506032b6570032100', 'hex');
+
+/**
+ * Ephemeral Ed25519 identity for authenticating the bridge connection
+ * with the local gateway. Generated once per bridge instance.
+ */
+class BridgeIdentity {
+  readonly deviceId: string;
+  readonly publicKeyBase64Url: string;
+  private readonly privateKey: crypto.KeyObject;
+
+  constructor() {
+    const { publicKey, privateKey } = crypto.generateKeyPairSync('ed25519');
+    this.privateKey = privateKey;
+    const spki = publicKey.export({ type: 'spki', format: 'der' }) as Buffer;
+    const raw = spki.subarray(ED25519_SPKI_PREFIX.length);
+    this.publicKeyBase64Url = base64UrlEncode(raw);
+    this.deviceId = crypto.createHash('sha256').update(raw).digest('hex');
+  }
+
+  sign(payload: string): string {
+    const sig = crypto.sign(null, Buffer.from(payload, 'utf8'), this.privateKey);
+    return base64UrlEncode(sig);
+  }
+}
+
+export interface BridgeSender {
+  /** Send a raw message to the remote device via relay */
+  sendRaw(data: string): void;
+}
+
+export class LocalBridge {
+  private ws: WsWebSocket | null = null;
+  private pendingMessages: string[] = [];
+  private readonly localGwUrl: string;
+  private readonly gatewayToken: string | undefined;
+  private readonly identity: BridgeIdentity;
+  private pingTimer: ReturnType<typeof setInterval> | null = null;
+  private pongTimer: ReturnType<typeof setTimeout> | null = null;
+
+  constructor(localGwUrl: string, gatewayToken?: string) {
+    this.localGwUrl = localGwUrl;
+    this.gatewayToken = gatewayToken;
+    this.identity = new BridgeIdentity();
+  }
+
+  /** Open a new WS connection to the local gateway, bridged to the relay sender */
+  open(sender: BridgeSender): void {
+    this.close();
+    this.pendingMessages = [];
+
+    const ws = new WsWebSocket(this.localGwUrl);
+
+    ws.on('open', () => {
+      console.log('[helmpilot-channel] Local gateway bridge opened');
+      for (const msg of this.pendingMessages) {
+        ws.send(msg);
+      }
+      this.pendingMessages = [];
+      this.startHeartbeat(ws);
+    });
+
+    ws.on('message', (data: Buffer | ArrayBuffer | Buffer[]) => {
+      const raw = typeof data === 'string' ? data : data.toString();
+      sender.sendRaw(raw);
+    });
+
+    ws.on('pong', () => {
+      // Pong received — clear the timeout
+      if (this.pongTimer) {
+        clearTimeout(this.pongTimer);
+        this.pongTimer = null;
+      }
+    });
+
+    ws.on('close', (code: number) => {
+      console.log(`[helmpilot-channel] Local gateway bridge closed: ${code}`);
+      this.stopHeartbeat();
+      this.ws = null;
+    });
+
+    ws.on('error', (err: Error) => {
+      console.error('[helmpilot-channel] Local gateway bridge error:', err.message);
+    });
+
+    this.ws = ws;
+  }
+
+  /** Forward a raw message from relay to the local gateway */
+  forward(data: string): void {
+    const msg = this.injectGatewayAuth(data);
+    if (this.ws && this.ws.readyState === 1 /* OPEN */) {
+      this.ws.send(msg);
+    } else {
+      // WS not yet open or not created — queue for flush when bridge opens
+      this.pendingMessages.push(msg);
+    }
+  }
+
+  /**
+   * If the message is a `connect` RPC, inject the local gateway auth token
+   * and re-sign the device identity using the bridge's own Ed25519 keypair.
+   *
+   * The remote device signed the challenge with an empty token (it doesn't
+   * know the gateway token). The gateway verifies the signature using
+   * `auth.token` — so we must re-sign with the real token for it to match.
+   */
+  private injectGatewayAuth(data: string): string {
+    try {
+      const frame = JSON.parse(data);
+      if (frame.method === 'connect' && frame.params) {
+        const token = this.gatewayToken || process.env.OPENCLAW_GATEWAY_TOKEN;
+        if (!token) return data;
+
+        const nonce = frame.params.device?.nonce;
+        if (!nonce) return data;
+
+        const signedAt = Date.now();
+        const scopes = Array.isArray(frame.params.scopes)
+          ? frame.params.scopes.join(',')
+          : '';
+
+        // Normalize platform/deviceFamily to lowercase (matches gateway's normalizeDeviceMetadataForAuth)
+        const platform = (frame.params.client?.platform || '').toLowerCase();
+        const deviceFamily = (frame.params.client?.deviceFamily || '').toLowerCase();
+
+        const payload = [
+          'v3',
+          this.identity.deviceId,
+          frame.params.client?.id || 'cli',
+          frame.params.client?.mode || 'ui',
+          frame.params.role || 'operator',
+          scopes,
+          String(signedAt),
+          token,
+          nonce,
+          platform,
+          deviceFamily,
+        ].join('|');
+
+        frame.params.auth = { ...(frame.params.auth || {}), token };
+        frame.params.device = {
+          id: this.identity.deviceId,
+          publicKey: this.identity.publicKeyBase64Url,
+          signature: this.identity.sign(payload),
+          signedAt,
+          nonce,
+        };
+
+        return JSON.stringify(frame);
+      }
+    } catch {
+      // Not JSON or parse error — forward as-is
+    }
+    return data;
+  }
+
+  /** Close the bridge connection and stop heartbeat */
+  close(): void {
+    this.stopHeartbeat();
+    if (this.ws) {
+      try { this.ws.close(1000, 'Bridge closed'); } catch {}
+      this.ws = null;
+    }
+  }
+
+  /** Start WS-level ping/pong heartbeat */
+  private startHeartbeat(ws: WsWebSocket): void {
+    this.stopHeartbeat();
+    this.pingTimer = setInterval(() => {
+      if (ws.readyState !== 1 /* OPEN */) return;
+      ws.ping();
+      this.pongTimer = setTimeout(() => {
+        console.warn('[helmpilot-channel] Local bridge: pong timeout, closing connection');
+        try { ws.terminate(); } catch {}
+      }, PONG_TIMEOUT_MS);
+    }, PING_INTERVAL_MS);
+  }
+
+  /** Stop heartbeat timers */
+  private stopHeartbeat(): void {
+    if (this.pingTimer) {
+      clearInterval(this.pingTimer);
+      this.pingTimer = null;
+    }
+    if (this.pongTimer) {
+      clearTimeout(this.pongTimer);
+      this.pongTimer = null;
+    }
+  }
+}