@omnixal/openclaw-nats-plugin 0.2.8 → 0.2.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omnixal/openclaw-nats-plugin",
-  "version": "0.2.8",
+  "version": "0.2.10",
   "description": "NATS JetStream event-driven plugin for OpenClaw",
   "license": "MIT",
   "type": "module",

package/sidecar/src/consumer/consumer.controller.ts

@@ -1,6 +1,6 @@
 import { Controller, BaseController, Subscribe, OnQueueReady, type Message } from '@onebun/core';
 import { PipelineService } from '../pre-handlers/pipeline.service';
-import { GatewayClientService } from '../gateway/gateway-client.service';
+import { GatewayClientService, GatewayRpcError } from '../gateway/gateway-client.service';
 import { PendingService } from '../pending/pending.service';
 import { RouterService } from '../router/router.service';
 import { MetricsService } from '../metrics/metrics.service';
@@ -73,6 +73,13 @@ export class ConsumerController extends BaseController {
             await this.logService.logDelivery(route.id, envelope.subject, JSON.stringify({ eventId: envelope.id, target: route.target }));
           } catch (routeErr) {
             await this.logService.logError('route', route.id, envelope.subject, routeErr);
+            // Gateway rejected the request (e.g. missing scope) — store in pending, don't nack
+            if (routeErr instanceof GatewayRpcError) {
+              this.logger.error(`Gateway rejected event ${envelope.id}: ${routeErr.errorCode} — ${routeErr.errorMessage}`);
+              await this.pendingService.addPending(envelope);
+              await message.ack();
+              return;
+            }
             throw routeErr;
           }
         }

package/sidecar/src/gateway/device-identity.ts

@@ -0,0 +1,146 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+export interface DeviceIdentity {
+  deviceId: string;
+  publicKeyPem: string;
+  privateKeyPem: string;
+}
+
+interface StoredIdentity {
+  version: 1;
+  deviceId: string;
+  publicKeyPem: string;
+  privateKeyPem: string;
+  createdAtMs: number;
+}
+
+export interface SignChallengeParams {
+  deviceId: string;
+  clientId: string;
+  clientMode: string;
+  role: string;
+  scopes: string[];
+  signedAtMs: number;
+  token: string;
+  nonce: string;
+  platform?: string;
+  deviceFamily?: string;
+}
+
+/** Ed25519 SPKI DER prefix (12 bytes) before the 32-byte raw public key */
+const ED25519_SPKI_PREFIX = Buffer.from('302a300506032b6570032100', 'hex');
+
+function base64UrlEncode(buf: Buffer): string {
+  return buf.toString('base64').replaceAll('+', '-').replaceAll('/', '_').replace(/=+$/g, '');
+}
+
+/** Extract raw 32-byte Ed25519 public key from PEM-encoded SPKI */
+function derivePublicKeyRaw(publicKeyPem: string): Buffer {
+  const key = crypto.createPublicKey(publicKeyPem);
+  const spki = key.export({ type: 'spki', format: 'der' }) as Buffer;
+  if (
+    spki.length === ED25519_SPKI_PREFIX.length + 32 &&
+    spki.subarray(0, ED25519_SPKI_PREFIX.length).equals(ED25519_SPKI_PREFIX)
+  ) {
+    return spki.subarray(ED25519_SPKI_PREFIX.length);
+  }
+  return spki;
+}
+
+/** Derive deviceId as SHA-256(rawPublicKey).hex — matches OpenClaw's deriveDeviceIdFromPublicKey */
+function fingerprintPublicKey(publicKeyPem: string): string {
+  const raw = derivePublicKeyRaw(publicKeyPem);
+  return crypto.createHash('sha256').update(raw).digest('hex');
+}
+
+/** Normalize metadata for auth payload — ASCII lowercase + trim (matches OpenClaw's normalizeDeviceMetadataForAuth) */
+function normalizeMetadata(value?: string | null): string {
+  if (typeof value !== 'string') return '';
+  const trimmed = value.trim();
+  if (!trimmed) return '';
+  return trimmed.replace(/[A-Z]/g, (c) => String.fromCharCode(c.charCodeAt(0) + 32));
+}
+
+/** Generate a new Ed25519 keypair and derive device identity */
+export function generateIdentity(): DeviceIdentity {
+  const { publicKey, privateKey } = crypto.generateKeyPairSync('ed25519');
+  const publicKeyPem = publicKey.export({ type: 'spki', format: 'pem' }).toString();
+  const privateKeyPem = privateKey.export({ type: 'pkcs8', format: 'pem' }).toString();
+  const deviceId = fingerprintPublicKey(publicKeyPem);
+  return { deviceId, publicKeyPem, privateKeyPem };
+}
+
+/** Load existing device identity from file, or generate and persist a new one */
+export function loadOrCreateIdentity(filePath: string): DeviceIdentity {
+  try {
+    if (fs.existsSync(filePath)) {
+      const raw = fs.readFileSync(filePath, 'utf8');
+      const parsed = JSON.parse(raw) as StoredIdentity;
+      if (
+        parsed?.version === 1 &&
+        typeof parsed.deviceId === 'string' &&
+        typeof parsed.publicKeyPem === 'string' &&
+        typeof parsed.privateKeyPem === 'string'
+      ) {
+        // Re-derive deviceId to handle corrupted stored IDs
+        const derivedId = fingerprintPublicKey(parsed.publicKeyPem);
+        return {
+          deviceId: derivedId,
+          publicKeyPem: parsed.publicKeyPem,
+          privateKeyPem: parsed.privateKeyPem,
+        };
+      }
+    }
+  } catch {
+    // fall through to regenerate
+  }
+
+  const identity = generateIdentity();
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const stored: StoredIdentity = {
+    version: 1,
+    deviceId: identity.deviceId,
+    publicKeyPem: identity.publicKeyPem,
+    privateKeyPem: identity.privateKeyPem,
+    createdAtMs: Date.now(),
+  };
+  fs.writeFileSync(filePath, `${JSON.stringify(stored, null, 2)}\n`, { mode: 0o600 });
+  return identity;
+}
+
+/** Get base64url-encoded raw public key (for the connect frame device.publicKey field) */
+export function publicKeyToBase64Url(publicKeyPem: string): string {
+  return base64UrlEncode(derivePublicKeyRaw(publicKeyPem));
+}
+
+/**
+ * Build v3 signature payload and sign it with Ed25519 private key.
+ * Returns base64url-encoded signature.
+ *
+ * v3 payload format: v3|deviceId|clientId|clientMode|role|scopes|signedAtMs|token|nonce|platform|deviceFamily
+ */
+export function signChallenge(privateKeyPem: string, params: SignChallengeParams): string {
+  const scopes = params.scopes.join(',');
+  const token = params.token ?? '';
+  const platform = normalizeMetadata(params.platform);
+  const deviceFamily = normalizeMetadata(params.deviceFamily);
+  const payload = [
+    'v3',
+    params.deviceId,
+    params.clientId,
+    params.clientMode,
+    params.role,
+    scopes,
+    String(params.signedAtMs),
+    token,
+    params.nonce,
+    platform,
+    deviceFamily,
+  ].join('|');
+
+  const key = crypto.createPrivateKey(privateKeyPem);
+  const sig = crypto.sign(null, Buffer.from(payload, 'utf8'), key);
+  return base64UrlEncode(sig);
+}

package/sidecar/src/gateway/gateway-client.service.ts

@@ -1,4 +1,6 @@
 import { Service, BaseService, type OnModuleInit, type OnModuleDestroy } from '@onebun/core';
+import path from 'node:path';
+import { loadOrCreateIdentity, publicKeyToBase64Url, signChallenge, type DeviceIdentity } from './device-identity';
 
 export interface GatewayInjectPayload {
   target: string;
@@ -40,12 +42,20 @@ export class GatewayClientService extends BaseService implements OnModuleInit, O
   private requestId = 0;
   private wsUrl!: string;
   private token!: string;
+  private identity!: DeviceIdentity;
+  private publicKeyBase64Url!: string;
+  private challengeNonce = '';
   private pendingRequests = new Map<string, PendingRequest>();
 
   async onModuleInit(): Promise<void> {
     this.wsUrl = this.config.get('gateway.wsUrl');
     this.token = this.config.get('gateway.token');
     if (this.wsUrl && this.token) {
+      const dbPath = this.config.get('database.url');
+      const identityPath = path.join(path.dirname(dbPath), 'device-identity.json');
+      this.identity = loadOrCreateIdentity(identityPath);
+      this.publicKeyBase64Url = publicKeyToBase64Url(this.identity.publicKeyPem);
+      this.logger.info('Device identity loaded', { deviceId: this.identity.deviceId });
       this.connect();
     } else {
       this.logger.warn('Gateway WebSocket not configured — skipping connection (need wsUrl + deviceToken)');
@@ -99,7 +109,8 @@ export class GatewayClientService extends BaseService implements OnModuleInit, O
 
     // Server challenge — respond with connect frame
     if (frame.type === 'event' && frame.event === 'connect.challenge') {
-      this.logger.debug('Received connect.challenge from server');
+      this.challengeNonce = frame.payload?.nonce ?? '';
+      this.logger.debug('Received connect.challenge from server', { hasNonce: !!this.challengeNonce });
       this.sendConnectFrame();
       return;
     }
@@ -117,7 +128,20 @@ export class GatewayClientService extends BaseService implements OnModuleInit, O
       if (payload?.type === 'hello-ok') {
         if (!this.connected) {
           this.connected = true;
-          this.logger.info('OpenClaw handshake complete — connected');
+          const grantedScopes = payload.auth?.scopes ?? [];
+          const serverVersion = payload.server?.version ?? 'unknown';
+          this.logger.info('OpenClaw handshake complete', {
+            protocol: payload.protocol,
+            serverVersion,
+            grantedScopes,
+            connId: payload.server?.connId,
+          });
+          if (grantedScopes.length > 0 && !grantedScopes.includes('operator.write')) {
+            this.logger.error(
+              `Gateway did NOT grant operator.write scope! Granted: [${grantedScopes.join(', ')}]. ` +
+              'Message delivery will fail. Rotate the device token with --scope operator.write',
+            );
+          }
         }
         return;
       }
@@ -149,33 +173,59 @@ export class GatewayClientService extends BaseService implements OnModuleInit, O
   private sendConnectFrame(): void {
     if (!this.ws || this.ws.readyState !== WebSocket.OPEN || this.connectSent) return;
     this.connectSent = true;
-    this.logger.info('Sending connect frame');
+
+    const signedAt = Date.now();
+    const scopes = ['operator.read', 'operator.write'];
+    const client = {
+      id: 'gateway-client' as const,
+      displayName: 'nats-sidecar',
+      version: '1.0.0',
+      platform: 'linux',
+      mode: 'backend' as const,
+    };
+
+    const signature = signChallenge(this.identity.privateKeyPem, {
+      deviceId: this.identity.deviceId,
+      clientId: client.id,
+      clientMode: client.mode,
+      role: 'operator',
+      scopes,
+      signedAtMs: signedAt,
+      token: this.token,
+      nonce: this.challengeNonce,
+      platform: client.platform,
+    });
+
+    this.logger.info('Sending connect frame with device identity', {
+      deviceId: this.identity.deviceId,
+    });
 
     try {
       this.send({
-      type: 'req',
-      id: `connect-${++this.requestId}`,
-      method: 'connect',
-      params: {
-        minProtocol: 3,
-        maxProtocol: 3,
-        client: {
-          id: 'gateway-client',
-          displayName: 'nats-sidecar',
-          version: '1.0.0',
-          platform: 'linux',
-          mode: 'backend',
+        type: 'req',
+        id: `connect-${++this.requestId}`,
+        method: 'connect',
+        params: {
+          minProtocol: 3,
+          maxProtocol: 3,
+          client,
+          role: 'operator',
+          scopes,
+          caps: [],
+          commands: [],
+          permissions: {},
+          auth: { token: this.token },
+          device: {
+            id: this.identity.deviceId,
+            publicKey: this.publicKeyBase64Url,
+            signature,
+            signedAt,
+            nonce: this.challengeNonce,
+          },
+          locale: 'en-US',
+          userAgent: 'nats-sidecar/1.0.0',
         },
-        role: 'operator',
-        scopes: ['operator.read', 'operator.write'],
-        caps: [],
-        commands: [],
-        permissions: {},
-        auth: { token: this.token },
-        locale: 'en-US',
-        userAgent: 'nats-sidecar/1.0.0',
-      },
-    });
+      });
     } catch (err) {
       this.logger.error('Failed to send connect frame', err);
       this.connectSent = false;