openclaw-client 2.0.1 → 2.1.1

package/src/client.ts

@@ -1,3 +1,7 @@
+import type { DeviceIdentityStore, DeviceTokenStore } from './device-identity';
+import { DeviceIdentityManager } from './device-identity';
+import type { ReconnectConfig } from './reconnect';
+import { ReconnectController } from './reconnect';
 import type {
   AgentIdentityParams,
   AgentIdentityResult,
@@ -120,8 +124,22 @@ export interface OpenClawClientConfig {
    *  Can be a static object or a function that receives the challenge
    *  (useful for signing the nonce into `device.nonce`). */
   connectParams?:
-    | Partial<ConnectParams>
-    | ((challenge: { nonce: string; ts: number }) => Partial<ConnectParams> | Promise<Partial<ConnectParams>>);
+  | Partial<ConnectParams>
+  | ((challenge: { nonce: string; ts: number }) => Partial<ConnectParams> | Promise<Partial<ConnectParams>>);
+  /** Provide a DeviceIdentityStore to enable built-in Ed25519 device signing.
+   *  When set, the library generates/loads a keypair and signs the connect
+   *  request automatically (takes precedence over connectParams function). */
+  deviceIdentity?: DeviceIdentityStore;
+  /** Optional store for persisting the device token returned by the gateway
+   *  after pairing approval. The stored token is preferred over config.token
+   *  for subsequent connections. */
+  deviceToken?: DeviceTokenStore;
+  /** Enable automatic reconnection with exponential backoff. */
+  reconnect?: ReconnectConfig;
+  /** Called when connection state changes. */
+  onConnection?: (connected: boolean) => void;
+  /** Called when the gateway indicates device pairing is required. */
+  onPairingRequired?: (required: boolean) => void;
 }
 
 export type EventListener = (event: EventFrame) => void;
@@ -148,9 +166,22 @@ export class OpenClawClient {
   private eventListeners: EventListener[] = [];
   private connected = false;
   private connectionId: string | null = null;
+  private deviceManager: DeviceIdentityManager | null = null;
+  private reconnectController: ReconnectController | null = null;
+  private reconnecting = false;
+  private intentionalDisconnect = false;
 
   constructor(config: OpenClawClientConfig) {
     this.config = config;
+    if (config.deviceIdentity) {
+      this.deviceManager = new DeviceIdentityManager(
+        config.deviceIdentity,
+        config.deviceToken,
+      );
+    }
+    if (config.reconnect?.enabled) {
+      this.reconnectController = new ReconnectController(config.reconnect);
+    }
   }
 
   /**
@@ -167,6 +198,8 @@ export class OpenClawClient {
       throw new Error('Already connected');
     }
 
+    this.intentionalDisconnect = false;
+
     // Create WebSocket connection
     const WS = getWebSocketConstructor();
     this.ws = new WS(this.config.gatewayUrl);
@@ -216,6 +249,14 @@ export class OpenClawClient {
     const result = await this.handshake(challenge);
     this.connected = true;
     this.connectionId = result.server.connId;
+
+    // Save device token if returned and store is configured
+    if (result.auth?.deviceToken && this.deviceManager) {
+      await this.deviceManager.saveDeviceToken(result.auth.deviceToken);
+    }
+
+    this.reconnectController?.reset();
+    this.config.onConnection?.(true);
     return result;
   }
 
@@ -223,12 +264,16 @@ export class OpenClawClient {
    * Disconnect from the Gateway
    */
   disconnect(): void {
+    this.intentionalDisconnect = true;
+    this.reconnectController?.abort();
+
     if (this.ws) {
       this.ws.close();
       this.ws = null;
     }
     this.connected = false;
     this.connectionId = null;
+    this.config.onConnection?.(false);
 
     // Reject all pending requests
     for (const [id, { reject }] of this.pending.entries()) {
@@ -269,21 +314,55 @@ export class OpenClawClient {
    * Uses connectTimeoutMs (default 120s) since device approval may take a while.
    */
   private async handshake(challenge: { nonce: string; ts: number }): Promise<HelloOk> {
-    const connectParams = typeof this.config.connectParams === 'function'
-      ? await this.config.connectParams(challenge)
-      : (this.config.connectParams ?? {});
+    const clientId = this.config.clientId || 'webchat-ui';
+    const clientMode = this.config.mode || 'ui';
+    const role = 'operator';
+    const scopes = ['operator.read', 'operator.write', 'operator.admin'];
+
+    let connectParams: Partial<ConnectParams> = {};
+
+    if (this.deviceManager) {
+      // Built-in device identity takes precedence over connectParams function
+      const storedToken = await this.deviceManager.getDeviceToken();
+      const token = storedToken || this.config.token;
+
+      const device = await this.deviceManager.buildConnectDevice({
+        clientId,
+        clientMode,
+        role,
+        scopes,
+        token,
+        nonce: challenge.nonce,
+      });
+
+      // Merge with static connectParams (for caps, etc.) but not function form
+      const staticParams =
+        typeof this.config.connectParams === 'function'
+          ? {}
+          : (this.config.connectParams ?? {});
+
+      connectParams = { ...staticParams, device };
+      // Override auth token if we have a stored device token
+      if (storedToken) {
+        connectParams.auth = { token: storedToken };
+      }
+    } else if (typeof this.config.connectParams === 'function') {
+      connectParams = await this.config.connectParams(challenge);
+    } else {
+      connectParams = this.config.connectParams ?? {};
+    }
 
     const params: ConnectParams = {
       minProtocol: 3,
       maxProtocol: 3,
       client: {
-        id: this.config.clientId || 'webchat-ui',
+        id: clientId,
         version: this.config.clientVersion || '1.0.0',
         platform: this.config.platform || 'web',
-        mode: this.config.mode || 'ui',
+        mode: clientMode,
       },
-      role: 'operator',
-      scopes: ['operator.read', 'operator.write', 'operator.admin'],
+      role,
+      scopes,
       auth: {
         token: this.config.token,
       },
@@ -382,6 +461,15 @@ export class OpenClawClient {
    * Handle event frame
    */
   private handleEvent(frame: EventFrame): void {
+    // Fire onPairingRequired for device pairing events
+    if (this.config.onPairingRequired) {
+      if (frame.event === 'device.pair.required') {
+        this.config.onPairingRequired(true);
+      } else if (frame.event === 'device.pair.approved') {
+        this.config.onPairingRequired(false);
+      }
+    }
+
     for (const listener of this.eventListeners) {
       try {
         listener(frame);
@@ -391,12 +479,63 @@ export class OpenClawClient {
     }
   }
 
+  private attemptReconnect(): void {
+    if (this.reconnecting) return;
+    this.reconnecting = true;
+
+    const loop = async () => {
+      while (
+        !this.intentionalDisconnect &&
+        this.reconnectController &&
+        this.reconnectController.canRetry()
+      ) {
+        try {
+          await this.reconnectController.schedule();
+        } catch {
+          // Aborted or max attempts exceeded
+          break;
+        }
+
+        if (this.intentionalDisconnect) break;
+
+        try {
+          await this.connect();
+          break; // Success
+        } catch {
+          // Will retry on next iteration
+        }
+      }
+      this.reconnecting = false;
+    };
+
+    loop();
+  }
+
   /**
    * Handle connection close
    */
   private handleClose(): void {
+    const wasConnected = this.connected;
     this.connected = false;
-    console.log('WebSocket connection closed');
+    this.connectionId = null;
+
+    if (wasConnected) {
+      this.config.onConnection?.(false);
+    }
+
+    // Reject all pending requests
+    for (const [id, { reject }] of this.pending.entries()) {
+      reject(new Error('Connection closed'));
+      this.pending.delete(id);
+    }
+
+    if (
+      !this.intentionalDisconnect &&
+      this.reconnectController &&
+      this.reconnectController.canRetry()
+    ) {
+      this.attemptReconnect();
+    }
   }
 
   /**
@@ -498,7 +637,7 @@ export class OpenClawClient {
    * Get agent identity
    */
   async getAgentIdentity(params: AgentIdentityParams = {}): Promise<AgentIdentityResult> {
-    return this.request<AgentIdentityResult>('agent.identity', params);
+    return this.request<AgentIdentityResult>('agent.identity.get', params);
   }
 
   /**

package/src/device-identity.ts

@@ -0,0 +1,131 @@
+export interface DeviceIdentityRecord {
+  /** Hex-encoded SHA-256 of the raw 32-byte public key */
+  id: string;
+  /** Base64url-encoded (no padding) raw 32-byte public key */
+  publicKey: string;
+  /** JWK of the Ed25519 private key (for re-import) */
+  privateKeyJwk: JsonWebKey;
+}
+
+export interface DeviceIdentityStore {
+  load(): Promise<DeviceIdentityRecord | null>;
+  save(record: DeviceIdentityRecord): Promise<void>;
+}
+
+export interface DeviceTokenStore {
+  load(): Promise<string | null>;
+  save(token: string): Promise<void>;
+}
+
+export interface BuildConnectDeviceOptions {
+  clientId: string;
+  clientMode: string;
+  role: string;
+  scopes: string[];
+  token: string;
+  nonce: string;
+}
+
+function base64urlEncode(bytes: Uint8Array): string {
+  let binary = '';
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+function hexEncode(bytes: Uint8Array): string {
+  return Array.from(bytes)
+    .map((b) => b.toString(16).padStart(2, '0'))
+    .join('');
+}
+
+async function generateEd25519Keypair(): Promise<CryptoKeyPair> {
+  return crypto.subtle.generateKey('Ed25519', true, [
+    'sign',
+    'verify',
+  ]) as Promise<CryptoKeyPair>;
+}
+
+async function deriveDeviceId(rawPublicKey: ArrayBuffer): Promise<string> {
+  const hash = await crypto.subtle.digest('SHA-256', rawPublicKey);
+  return hexEncode(new Uint8Array(hash));
+}
+
+async function signV2Payload(
+  privateKeyJwk: JsonWebKey,
+  payload: string,
+): Promise<string> {
+  const key = await crypto.subtle.importKey(
+    'jwk',
+    privateKeyJwk,
+    'Ed25519',
+    false,
+    ['sign'],
+  );
+  const data = new TextEncoder().encode(payload);
+  const signature = await crypto.subtle.sign('Ed25519', key, data);
+  return base64urlEncode(new Uint8Array(signature));
+}
+
+export class DeviceIdentityManager {
+  private identityStore: DeviceIdentityStore;
+  private tokenStore: DeviceTokenStore | null;
+
+  constructor(
+    identityStore: DeviceIdentityStore,
+    tokenStore?: DeviceTokenStore,
+  ) {
+    this.identityStore = identityStore;
+    this.tokenStore = tokenStore ?? null;
+  }
+
+  async getOrCreateIdentity(): Promise<DeviceIdentityRecord> {
+    const existing = await this.identityStore.load();
+    if (existing) return existing;
+
+    const keypair = await generateEd25519Keypair();
+    const rawPublicKey = await crypto.subtle.exportKey('raw', keypair.publicKey);
+    const privateKeyJwk = await crypto.subtle.exportKey('jwk', keypair.privateKey);
+    const id = await deriveDeviceId(rawPublicKey);
+    const publicKey = base64urlEncode(new Uint8Array(rawPublicKey));
+
+    const record: DeviceIdentityRecord = { id, publicKey, privateKeyJwk };
+    await this.identityStore.save(record);
+    return record;
+  }
+
+  async buildConnectDevice(
+    opts: BuildConnectDeviceOptions,
+  ): Promise<{
+    id: string;
+    publicKey: string;
+    signature: string;
+    signedAt: number;
+    nonce: string;
+  }> {
+    const identity = await this.getOrCreateIdentity();
+    const signedAt = Date.now();
+    const scopeStr = opts.scopes.join(',');
+    const payload = `v2|${identity.id}|${opts.clientId}|${opts.clientMode}|${opts.role}|${scopeStr}|${signedAt}|${opts.token}|${opts.nonce}`;
+    const signature = await signV2Payload(identity.privateKeyJwk, payload);
+
+    return {
+      id: identity.id,
+      publicKey: identity.publicKey,
+      signature,
+      signedAt,
+      nonce: opts.nonce,
+    };
+  }
+
+  async getDeviceToken(): Promise<string | null> {
+    if (!this.tokenStore) return null;
+    return this.tokenStore.load();
+  }
+
+  async saveDeviceToken(token: string): Promise<void> {
+    if (!this.tokenStore) return;
+    await this.tokenStore.save(token);
+  }
+}

package/src/index.ts

@@ -1,3 +1,5 @@
 export * from './client';
+export * from './device-identity';
+export * from './reconnect';
 export * from './server-client';
 export * from './types';

package/src/reconnect.ts

@@ -0,0 +1,68 @@
+export interface ReconnectConfig {
+  enabled: boolean;
+  /** Base delay in ms (default: 1000) */
+  baseDelay?: number;
+  /** Maximum delay in ms (default: 30000) */
+  maxDelay?: number;
+  /** Maximum number of reconnect attempts (default: Infinity) */
+  maxAttempts?: number;
+}
+
+export class ReconnectController {
+  private baseDelay: number;
+  private maxDelay: number;
+  private maxAttempts: number;
+  private attempt = 0;
+  private aborted = false;
+  private pendingTimer: ReturnType<typeof setTimeout> | null = null;
+
+  constructor(config: ReconnectConfig) {
+    this.baseDelay = config.baseDelay ?? 1000;
+    this.maxDelay = config.maxDelay ?? 30000;
+    this.maxAttempts = config.maxAttempts ?? Infinity;
+  }
+
+  nextDelay(): number | null {
+    if (this.aborted || this.attempt >= this.maxAttempts) return null;
+    const exponential = Math.min(
+      this.baseDelay * Math.pow(2, this.attempt),
+      this.maxDelay,
+    );
+    // Jitter: random between 50%-100% of the exponential value
+    const jitter = 0.5 + Math.random() * 0.5;
+    this.attempt++;
+    return Math.round(exponential * jitter);
+  }
+
+  schedule(): Promise<void> {
+    const delay = this.nextDelay();
+    if (delay === null) return Promise.reject(new Error('Max reconnect attempts exceeded'));
+    return new Promise((resolve, reject) => {
+      this.pendingTimer = setTimeout(() => {
+        this.pendingTimer = null;
+        if (this.aborted) {
+          reject(new Error('Reconnect aborted'));
+        } else {
+          resolve();
+        }
+      }, delay);
+    });
+  }
+
+  reset(): void {
+    this.attempt = 0;
+    this.aborted = false;
+  }
+
+  abort(): void {
+    this.aborted = true;
+    if (this.pendingTimer !== null) {
+      clearTimeout(this.pendingTimer);
+      this.pendingTimer = null;
+    }
+  }
+
+  canRetry(): boolean {
+    return !this.aborted && this.attempt < this.maxAttempts;
+  }
+}