@honor-claw/yoyo 0.0.1-alpha.0

package/src/gateway-client/device/builder.ts

@@ -0,0 +1,105 @@
+import { GATEWAY_CLIENT_MODES, GATEWAY_CLIENT_NAMES } from "../types.js";
+import { buildDeviceAuthPayloadV3 } from "./auth.js";
+import {
+  publicKeyRawBase64UrlFromPem,
+  signDevicePayload,
+} from "./identity.js";
+import {
+  type DeviceBuilderOptions,
+  type DeviceInfo,
+} from "./types.js";
+
+/**
+ * Build device information for gateway connection
+ * This is the main function to generate device authentication data
+ *
+ * @param options - Device builder options
+ * @returns Device information object or undefined if no device identity provided
+ *
+ * @example
+ * ```typescript
+ * const deviceInfo = buildDeviceInfo({
+ *   deviceIdentity: loadOrCreateDeviceIdentity(),
+ *   clientName: "my-client",
+ *   role: "node",
+ *   scopes: ["node.invoke"],
+ *   nonce: "challenge-nonce",
+ *   platform: "ios",
+ *   deviceFamily: "iPhone"
+ * });
+ * ```
+ */
+export function buildDeviceInfo(options: DeviceBuilderOptions): DeviceInfo | undefined {
+  const {
+    deviceIdentity,
+    clientName = GATEWAY_CLIENT_NAMES.GATEWAY_CLIENT,
+    clientMode = GATEWAY_CLIENT_MODES.BACKEND,
+    role = "operator",
+    scopes = ["operator.admin"],
+    platform = process.platform,
+    deviceFamily,
+    authToken = null,
+    nonce,
+    signedAtMs = Date.now(),
+  } = options;
+
+  if (!deviceIdentity) {
+    return undefined;
+  }
+
+  // Build authentication payload
+  const payload = buildDeviceAuthPayloadV3({
+    deviceId: deviceIdentity.deviceId,
+    clientId: clientName,
+    clientMode,
+    role,
+    scopes,
+    signedAtMs,
+    token: authToken,
+    nonce,
+    platform,
+    deviceFamily,
+  });
+
+  // Sign the payload
+  const signature = signDevicePayload(deviceIdentity.privateKeyPem, payload);
+
+  // Return device information
+  return {
+    id: deviceIdentity.deviceId,
+    publicKey: publicKeyRawBase64UrlFromPem(deviceIdentity.publicKeyPem),
+    signature,
+    signedAt: signedAtMs,
+    nonce,
+  };
+}
+
+/**
+ * Build device information for node role
+ * Convenience function for node connections
+ *
+ * @param options - Device builder options
+ * @returns Device information object or undefined
+ */
+export function buildNodeDeviceInfo(options: Omit<DeviceBuilderOptions, "role">): DeviceInfo | undefined {
+  return buildDeviceInfo({
+    ...options,
+    role: "node",
+    scopes: options.scopes ?? ["node.invoke"],
+  });
+}
+
+/**
+ * Build device information for operator role
+ * Convenience function for operator connections
+ *
+ * @param options - Device builder options
+ * @returns Device information object or undefined
+ */
+export function buildOperatorDeviceInfo(options: Omit<DeviceBuilderOptions, "role">): DeviceInfo | undefined {
+  return buildDeviceInfo({
+    ...options,
+    role: "operator",
+    scopes: options.scopes ?? ["operator.admin"],
+  });
+}

package/src/gateway-client/device/helpers.ts

@@ -0,0 +1,40 @@
+/**
+ * Normalize device metadata for authentication payloads
+ * Keeps cross-runtime normalization deterministic (TS/Swift/Kotlin)
+ * by only lowercasing ASCII metadata fields used in auth payloads.
+ */
+function normalizeTrimmedMetadata(value?: string | null): string {
+  if (typeof value !== "string") {
+    return "";
+  }
+  const trimmed = value.trim();
+  return trimmed ? trimmed : "";
+}
+
+function toLowerAscii(input: string): string {
+  return input.replace(/[A-Z]/g, (char) => String.fromCharCode(char.charCodeAt(0) + 32));
+}
+
+export function normalizeDeviceMetadataForAuth(value?: string | null): string {
+  const trimmed = normalizeTrimmedMetadata(value);
+  if (!trimmed) {
+    return "";
+  }
+  // Keep cross-runtime normalization deterministic (TS/Swift/Kotlin) by only
+  // lowercasing ASCII metadata fields used in auth payloads.
+  return toLowerAscii(trimmed);
+}
+
+/**
+ * Normalize device metadata for policy classification
+ * Collapses Unicode confusables to stable ASCII-like tokens before matching platform/family rules.
+ */
+export function normalizeDeviceMetadataForPolicy(value?: string | null): string {
+  const trimmed = normalizeTrimmedMetadata(value);
+  if (!trimmed) {
+    return "";
+  }
+  // Policy classification should collapse Unicode confusables to stable ASCII-ish
+  // tokens where possible before matching platform/family rules.
+  return trimmed.normalize("NFKD").replace(/\p{M}/gu, "").toLowerCase();
+}

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

@@ -0,0 +1,251 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import type { DeviceIdentity } from "./types.js";
+
+type StoredIdentity = {
+  version: 1;
+  deviceId: string;
+  publicKeyPem: string;
+  privateKeyPem: string;
+  createdAtMs: number;
+};
+
+/**
+ * Resolve default identity path
+ * Uses OS-specific state directory
+ */
+function resolveDefaultIdentityPath(): string {
+  const platform = process.platform;
+  let stateDir: string;
+
+  if (platform === "darwin") {
+    stateDir = path.join(os.homedir(), "Library", "Application Support", "xh-gateway-client");
+  } else if (platform === "win32") {
+    stateDir = path.join(os.homedir(), "AppData", "Local", "xh-gateway-client");
+  } else {
+    // Linux and others
+    stateDir = process.env.XDG_STATE_HOME
+      ? path.join(process.env.XDG_STATE_HOME, "xh-gateway-client")
+      : path.join(os.homedir(), ".local", "state", "xh-gateway-client");
+  }
+
+  return path.join(stateDir, "identity", "device.json");
+}
+
+/**
+ * Ensure directory exists
+ */
+function ensureDir(filePath: string): void {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+}
+
+/**
+ * ED25519 SPKI prefix for public key extraction
+ */
+const ED25519_SPKI_PREFIX = Buffer.from("302a300506032b6570032100", "hex");
+
+/**
+ * Base64 URL encode a buffer
+ */
+function base64UrlEncode(buf: Buffer): string {
+  return buf.toString("base64").replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/g, "");
+}
+
+/**
+ * Base64 URL decode a string
+ */
+function base64UrlDecode(input: string): Buffer {
+  const normalized = input.replaceAll("-", "+").replaceAll("_", "/");
+  const padded = normalized + "=".repeat((4 - (normalized.length % 4)) % 4);
+  return Buffer.from(padded, "base64");
+}
+
+/**
+ * Derive raw public key from PEM format
+ */
+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;
+}
+
+/**
+ * Generate fingerprint from public key
+ */
+function fingerprintPublicKey(publicKeyPem: string): string {
+  const raw = derivePublicKeyRaw(publicKeyPem);
+  return crypto.createHash("sha256").update(raw).digest("hex");
+}
+
+/**
+ * Generate a new device identity with ED25519 key pair
+ */
+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 or create device identity from file
+ * @param filePath - Optional path to identity file (defaults to OS-specific location)
+ * @returns Device identity
+ */
+export function loadOrCreateDeviceIdentity(
+  filePath: string = resolveDefaultIdentityPath(),
+): 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"
+      ) {
+        const derivedId = fingerprintPublicKey(parsed.publicKeyPem);
+        if (derivedId && derivedId !== parsed.deviceId) {
+          // Update stored deviceId if it doesn't match fingerprint
+          const updated: StoredIdentity = {
+            ...parsed,
+            deviceId: derivedId,
+          };
+          fs.writeFileSync(filePath, `${JSON.stringify(updated, null, 2)}\n`, { mode: 0o600 });
+          try {
+            fs.chmodSync(filePath, 0o600);
+          } catch {
+            // best-effort
+          }
+          return {
+            deviceId: derivedId,
+            publicKeyPem: parsed.publicKeyPem,
+            privateKeyPem: parsed.privateKeyPem,
+          };
+        }
+        return {
+          deviceId: parsed.deviceId,
+          publicKeyPem: parsed.publicKeyPem,
+          privateKeyPem: parsed.privateKeyPem,
+        };
+      }
+    }
+  } catch {
+    // fall through to regenerate on error
+  }
+
+  // Generate new identity
+  const identity = generateIdentity();
+  ensureDir(filePath);
+  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 });
+  try {
+    fs.chmodSync(filePath, 0o600);
+  } catch {
+    // best-effort
+  }
+  return identity;
+}
+
+/**
+ * Sign a payload using device private key
+ * @param privateKeyPem - Private key in PEM format
+ * @param payload - Payload string to sign
+ * @returns Base64 URL encoded signature
+ */
+export function signDevicePayload(privateKeyPem: string, payload: string): string {
+  const key = crypto.createPrivateKey(privateKeyPem);
+  const sig = crypto.sign(null, Buffer.from(payload, "utf8"), key);
+  return base64UrlEncode(sig);
+}
+
+/**
+ * Normalize device public key to base64 URL format
+ * @param publicKey - Public key in PEM or base64 format
+ * @returns Base64 URL encoded public key or null on error
+ */
+export function normalizeDevicePublicKeyBase64Url(publicKey: string): string | null {
+  try {
+    if (publicKey.includes("BEGIN")) {
+      return base64UrlEncode(derivePublicKeyRaw(publicKey));
+    }
+    const raw = base64UrlDecode(publicKey);
+    return base64UrlEncode(raw);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Derive device ID from public key
+ * @param publicKey - Public key in PEM or base64 format
+ * @returns Device ID (SHA256 hash) or null on error
+ */
+export function deriveDeviceIdFromPublicKey(publicKey: string): string | null {
+  try {
+    const raw = publicKey.includes("BEGIN")
+      ? derivePublicKeyRaw(publicKey)
+      : base64UrlDecode(publicKey);
+    return crypto.createHash("sha256").update(raw).digest("hex");
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Convert public key PEM to raw base64 URL format
+ * @param publicKeyPem - Public key in PEM format
+ * @returns Base64 URL encoded raw public key
+ */
+export function publicKeyRawBase64UrlFromPem(publicKeyPem: string): string {
+  return base64UrlEncode(derivePublicKeyRaw(publicKeyPem));
+}
+
+/**
+ * Verify device signature
+ * @param publicKey - Public key in PEM or base64 format
+ * @param payload - Original payload string
+ * @param signatureBase64Url - Base64 URL encoded signature
+ * @returns True if signature is valid, false otherwise
+ */
+export function verifyDeviceSignature(
+  publicKey: string,
+  payload: string,
+  signatureBase64Url: string,
+): boolean {
+  try {
+    const key = publicKey.includes("BEGIN")
+      ? crypto.createPublicKey(publicKey)
+      : crypto.createPublicKey({
+          key: Buffer.concat([ED25519_SPKI_PREFIX, base64UrlDecode(publicKey)]),
+          type: "spki",
+          format: "der",
+        });
+    const sig = (() => {
+      try {
+        return base64UrlDecode(signatureBase64Url);
+      } catch {
+        return Buffer.from(signatureBase64Url, "base64");
+      }
+    })();
+    return crypto.verify(null, Buffer.from(payload, "utf8"), key, sig);
+  } catch {
+    return false;
+  }
+}

package/src/gateway-client/device/index.ts

@@ -0,0 +1,40 @@
+/**
+ * XH Gateway Client
+ *
+ * A library for device authentication and gateway connection utilities.
+ * Provides device identity management, authentication payload building,
+ * and device information generation for OpenClaw gateway connections.
+ */
+
+// Types
+export type {
+  DeviceIdentity,
+  DeviceAuthPayloadParams,
+  DeviceAuthPayloadV3Params,
+  DeviceInfo,
+  DeviceBuilderOptions,
+} from "./types.js";
+
+// Device identity management
+export {
+  loadOrCreateDeviceIdentity,
+  signDevicePayload,
+  normalizeDevicePublicKeyBase64Url,
+  deriveDeviceIdFromPublicKey,
+  publicKeyRawBase64UrlFromPem,
+  verifyDeviceSignature,
+} from "./identity.js";
+
+// Device authentication
+export {
+  buildDeviceAuthPayload,
+  buildDeviceAuthPayloadV3,
+  normalizeDeviceMetadataForAuth,
+} from "./auth.js";
+
+// Device builder
+export {
+  buildDeviceInfo,
+  buildNodeDeviceInfo,
+  buildOperatorDeviceInfo,
+} from "./builder.js";

package/src/gateway-client/device/types.ts

@@ -0,0 +1,57 @@
+/**
+ * Device identity information
+ */
+export type DeviceIdentity = {
+  deviceId: string;
+  publicKeyPem: string;
+  privateKeyPem: string;
+};
+
+/**
+ * Device authentication payload parameters
+ */
+export type DeviceAuthPayloadParams = {
+  deviceId: string;
+  clientId: string;
+  clientMode: string;
+  role: string;
+  scopes: string[];
+  signedAtMs: number;
+  token?: string | null;
+  nonce: string;
+};
+
+/**
+ * Device authentication payload V3 parameters (with platform/device family)
+ */
+export type DeviceAuthPayloadV3Params = DeviceAuthPayloadParams & {
+  platform?: string | null;
+  deviceFamily?: string | null;
+};
+
+/**
+ * Device information for gateway connection
+ */
+export type DeviceInfo = {
+  id: string;
+  publicKey: string;
+  signature: string;
+  signedAt: number;
+  nonce: string;
+};
+
+/**
+ * Device builder options
+ */
+export type DeviceBuilderOptions = {
+  deviceIdentity?: DeviceIdentity;
+  clientName?: string;
+  clientMode?: string;
+  role?: string;
+  scopes?: string[];
+  platform?: string;
+  deviceFamily?: string;
+  authToken?: string | null;
+  nonce: string;
+  signedAtMs?: number;
+};

package/src/gateway-client/index.ts

@@ -0,0 +1,2 @@
+export * from "./client.js";
+export * from "./types.js"

package/src/gateway-client/types.deprecated.ts

@@ -0,0 +1,217 @@
+// ==================== 类型定义 ====================
+
+/**
+ * Gateway Client ID 枚举
+ */
+export const GATEWAY_CLIENT_IDS = {
+  WEBCHAT_UI: "webchat-ui",
+  CONTROL_UI: "openclaw-control-ui",
+  WEBCHAT: "webchat",
+  CLI: "cli",
+  GATEWAY_CLIENT: "gateway-client",
+  MACOS_APP: "openclaw-macos",
+  IOS_APP: "openclaw-ios",
+  ANDROID_APP: "openclaw-android",
+  NODE_HOST: "node-host",
+  TEST: "test",
+  FINGERPRINT: "fingerprint",
+  PROBE: "openclaw-probe",
+} as const;
+
+/**
+ * Gateway Client Mode 枚举
+ */
+export const GATEWAY_CLIENT_MODES = {
+  WEBCHAT: "webchat",
+  CLI: "cli",
+  UI: "ui",
+  BACKEND: "backend",
+  NODE: "node",
+  PROBE: "probe",
+  TEST: "test",
+} as const;
+
+/**
+ * Gateway Client ID 类型
+ */
+export type GatewayClientId =
+  (typeof GATEWAY_CLIENT_IDS)[keyof typeof GATEWAY_CLIENT_IDS];
+
+/**
+ * Gateway Client Mode 类型
+ */
+export type GatewayClientMode =
+  (typeof GATEWAY_CLIENT_MODES)[keyof typeof GATEWAY_CLIENT_MODES];
+
+/**
+ * Back-compat naming (internal): these values are IDs, not display names.
+ */
+export const GATEWAY_CLIENT_NAMES = GATEWAY_CLIENT_IDS;
+export type GatewayClientName = GatewayClientId;
+
+/**
+ * Gateway Client Info 类型
+ */
+export type GatewayClientInfo = {
+  id: GatewayClientId;
+  displayName?: string;
+  version: string;
+  platform: string;
+  deviceFamily?: string;
+  modelIdentifier?: string;
+  mode: GatewayClientMode;
+  instanceId?: string;
+};
+
+/**
+ * Gateway Client Cap 枚举
+ */
+export const GATEWAY_CLIENT_CAPS = {
+  TOOL_EVENTS: "tool-events",
+} as const;
+
+export type GatewayClientCap =
+  (typeof GATEWAY_CLIENT_CAPS)[keyof typeof GATEWAY_CLIENT_CAPS];
+
+const GATEWAY_CLIENT_ID_SET = new Set<GatewayClientId>(
+  Object.values(GATEWAY_CLIENT_IDS)
+);
+const GATEWAY_CLIENT_MODE_SET = new Set<GatewayClientMode>(
+  Object.values(GATEWAY_CLIENT_MODES)
+);
+
+export function normalizeGatewayClientId(
+  raw?: string | null
+): GatewayClientId | undefined {
+  const normalized = raw?.trim().toLowerCase();
+  if (!normalized) {
+    return undefined;
+  }
+  return GATEWAY_CLIENT_ID_SET.has(normalized as GatewayClientId)
+    ? (normalized as GatewayClientId)
+    : undefined;
+}
+
+export function normalizeGatewayClientName(
+  raw?: string | null
+): GatewayClientName | undefined {
+  return normalizeGatewayClientId(raw);
+}
+
+export function normalizeGatewayClientMode(
+  raw?: string | null
+): GatewayClientMode | undefined {
+  const normalized = raw?.trim().toLowerCase();
+  if (!normalized) {
+    return undefined;
+  }
+  return GATEWAY_CLIENT_MODE_SET.has(normalized as GatewayClientMode)
+    ? (normalized as GatewayClientMode)
+    : undefined;
+}
+
+export function hasGatewayClientCap(
+  caps: string[] | null | undefined,
+  cap: GatewayClientCap
+): boolean {
+  if (!Array.isArray(caps)) {
+    return false;
+  }
+  return caps.includes(cap);
+}
+
+/**
+ * 协议帧类型 - 请求帧
+ */
+export interface RequestFrame {
+  type: "req";
+  id: string;
+  method: string;
+  params?: unknown;
+}
+
+/**
+ * 协议帧类型 - 响应帧
+ */
+export interface ResponseFrame {
+  type: "res";
+  id: string;
+  ok: boolean;
+  payload?: unknown;
+  error?: {
+    code: number;
+    message: string;
+    details?: unknown;
+    retryable?: boolean;
+    retryAfterMs?: boolean;
+  };
+}
+
+/**
+ * 协议帧类型 - 事件帧
+ */
+export interface EventFrame {
+  type: "evt" | "event";
+  event: string;
+  seq?: number;
+  payload?: unknown;
+}
+
+/**
+ * 连接成功响应
+ */
+export interface HelloOk {
+  type: "hello-ok";
+  protocol: number;
+  gateway: {
+    id: string;
+    version: string;
+  };
+  auth?: {
+    deviceToken?: string;
+    role?: string;
+    scopes?: string[];
+  };
+  policy?: {
+    tickIntervalMs?: number;
+  };
+}
+
+/**
+ * 连接参数（简化版）
+ */
+export interface ConnectParams {
+  minProtocol?: number;
+  maxProtocol?: number;
+  client: {
+    id: GatewayClientId;
+    displayName?: string;
+    version?: string;
+    platform?: string;
+    deviceFamily?: string;
+    modelIdentifier?: string;
+    mode: GatewayClientMode;
+    instanceId?: string;
+  };
+  caps?: string[];
+  commands?: string[];
+  permissions?: Record<string, boolean>;
+  pathEnv?: string;
+  role?: string;
+  scopes?: string[];
+  device?: {
+    id: string;
+    publicKey: string;
+    signature: string;
+    signedAt: number;
+    nonce: string;
+  };
+  auth?: {
+    token?: string;
+    deviceToken?: string;
+    password?: string;
+  };
+  modelIdentifier?: string;
+  locale?: string;
+  userAgent?: string;
+}