@cavi-ai/api-client 0.1.0

package/src/core/gateway/rpc/device-crypto.ts

@@ -0,0 +1,101 @@
+// CANONICAL — single source of truth lives here. Do not duplicate. See packages/README.md.
+
+// Device identity crypto utilities for the gateway client.
+// Uses Web Crypto API (SubtleCrypto) for Ed25519 key generation, signing, and ID derivation.
+// Pure functions — no side effects, no storage.
+
+// --- Base64url ---
+
+export function base64UrlEncode(buf: Uint8Array): string {
+  let binary = "";
+  for (const byte of buf) {
+    binary += String.fromCharCode(byte);
+  }
+  return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+}
+
+export function base64UrlDecode(input: string): Uint8Array {
+  const normalized = input.replaceAll("-", "+").replaceAll("_", "/");
+  const padded = normalized + "=".repeat((4 - (normalized.length % 4)) % 4);
+  const binary = atob(padded);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}
+
+// --- Key Generation ---
+
+export async function generateDeviceKeypair(): Promise<CryptoKeyPair> {
+  return await crypto.subtle.generateKey("Ed25519", false, ["sign", "verify"]);
+}
+
+// --- Key Export ---
+
+export async function exportPublicKeyRaw(key: CryptoKey): Promise<Uint8Array> {
+  const raw = await crypto.subtle.exportKey("raw", key);
+  return new Uint8Array(raw);
+}
+
+// --- Device ID ---
+
+export async function deriveDeviceId(publicKeyRaw: Uint8Array): Promise<string> {
+  const hash = await crypto.subtle.digest("SHA-256", publicKeyRaw as ArrayBufferView<ArrayBuffer>);
+  const bytes = new Uint8Array(hash);
+  return Array.from(bytes)
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+// --- Payload ---
+
+function normalizeMetadata(value: string | undefined | null): string {
+  if (typeof value !== "string") {
+    return "";
+  }
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return "";
+  }
+  // Must match server's normalizeDeviceMetadataForAuth: ASCII lowercase only.
+  return trimmed.replace(/[A-Z]/g, (c) => String.fromCharCode(c.charCodeAt(0) + 32));
+}
+
+export function buildDeviceAuthPayloadV3(params: {
+  deviceId: string;
+  clientId: string;
+  clientMode: string;
+  role: string;
+  scopes: string[];
+  signedAtMs: number;
+  token: string;
+  nonce: string;
+  platform?: string | null;
+  deviceFamily?: string | null;
+}): string {
+  const scopes = params.scopes.join(",");
+  const platform = normalizeMetadata(params.platform);
+  const deviceFamily = normalizeMetadata(params.deviceFamily);
+  return [
+    "v3",
+    params.deviceId,
+    params.clientId,
+    params.clientMode,
+    params.role,
+    scopes,
+    String(params.signedAtMs),
+    params.token,
+    params.nonce,
+    platform,
+    deviceFamily,
+  ].join("|");
+}
+
+// --- Signing ---
+
+export async function signPayload(privateKey: CryptoKey, payload: string): Promise<string> {
+  const encoded = new TextEncoder().encode(payload);
+  const signature = await crypto.subtle.sign("Ed25519", privateKey, encoded);
+  return base64UrlEncode(new Uint8Array(signature));
+}

package/src/core/gateway/rpc/device-store.ts

@@ -0,0 +1,147 @@
+// CANONICAL — single source of truth lives here. Do not duplicate. See packages/README.md.
+
+// Device identity persistent store.
+// Private key: non-extractable CryptoKey in IndexedDB (never leaves crypto subsystem).
+// Device ID: SHA-256 hex in localStorage (public, fast lookup).
+
+import {
+  generateDeviceKeypair,
+  exportPublicKeyRaw,
+  deriveDeviceId,
+  base64UrlEncode,
+} from "./device-crypto.js";
+
+const IDB_NAME = "openclaw-device-identity";
+const IDB_STORE = "keys";
+const IDB_KEY = "current";
+const LS_KEY = "openclaw-device-id";
+
+export type DeviceIdentity = {
+  deviceId: string;
+  privateKey: CryptoKey;
+  publicKeyBase64Url: string;
+};
+
+type StoredEntry = {
+  deviceId: string;
+  publicKeyRaw: string;
+  keyPair: CryptoKeyPair;
+  createdAtMs: number;
+};
+
+// --- SubtleCrypto + IndexedDB availability ---
+
+export function isDeviceIdentitySupported(): boolean {
+  try {
+    return (
+      typeof globalThis.crypto?.subtle?.generateKey === "function" &&
+      typeof globalThis.indexedDB?.open === "function"
+    );
+  } catch {
+    return false;
+  }
+}
+
+// --- IndexedDB helpers ---
+
+function openDb(): Promise<IDBDatabase> {
+  return new Promise((resolve, reject) => {
+    const request = indexedDB.open(IDB_NAME, 1);
+    request.addEventListener("upgradeneeded", () => {
+      const db = request.result;
+      if (!db.objectStoreNames.contains(IDB_STORE)) {
+        db.createObjectStore(IDB_STORE);
+      }
+    });
+    request.addEventListener("success", () => resolve(request.result));
+    request.addEventListener("error", () => reject(request.error));
+  });
+}
+
+function idbGet(db: IDBDatabase, key: string): Promise<StoredEntry | undefined> {
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction(IDB_STORE, "readonly");
+    const store = tx.objectStore(IDB_STORE);
+    const request = store.get(key);
+    request.addEventListener("success", () => resolve(request.result as StoredEntry | undefined));
+    request.addEventListener("error", () => reject(request.error));
+  });
+}
+
+function idbPut(db: IDBDatabase, key: string, value: StoredEntry): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction(IDB_STORE, "readwrite");
+    const store = tx.objectStore(IDB_STORE);
+    const request = store.put(value, key);
+    request.addEventListener("success", () => resolve());
+    request.addEventListener("error", () => reject(request.error));
+  });
+}
+
+// --- Load or Create ---
+
+export async function loadOrCreateDeviceIdentity(): Promise<DeviceIdentity | null> {
+  if (!isDeviceIdentitySupported()) {
+    return null;
+  }
+
+  let db: IDBDatabase;
+  try {
+    db = await openDb();
+  } catch {
+    return null;
+  }
+
+  try {
+    // Try loading existing identity
+    const existing = await idbGet(db, IDB_KEY);
+    if (
+      existing &&
+      typeof existing.deviceId === "string" &&
+      typeof existing.publicKeyRaw === "string" &&
+      existing.keyPair?.privateKey instanceof CryptoKey
+    ) {
+      return {
+        deviceId: existing.deviceId,
+        privateKey: existing.keyPair.privateKey,
+        publicKeyBase64Url: existing.publicKeyRaw,
+      };
+    }
+  } catch {
+    // Corrupt entry — fall through to regenerate
+  }
+
+  // Generate new identity
+  try {
+    const keyPair = await generateDeviceKeypair();
+    const publicKeyRaw = await exportPublicKeyRaw(keyPair.publicKey);
+    const deviceId = await deriveDeviceId(publicKeyRaw);
+    const publicKeyBase64Url = base64UrlEncode(publicKeyRaw);
+
+    const entry: StoredEntry = {
+      deviceId,
+      publicKeyRaw: publicKeyBase64Url,
+      keyPair,
+      createdAtMs: Date.now(),
+    };
+
+    await idbPut(db, IDB_KEY, entry);
+
+    // Device ID in localStorage for quick existence check
+    try {
+      localStorage.setItem(LS_KEY, deviceId);
+    } catch {
+      // localStorage blocked — non-fatal
+    }
+
+    return {
+      deviceId,
+      privateKey: keyPair.privateKey,
+      publicKeyBase64Url,
+    };
+  } catch {
+    return null;
+  } finally {
+    db.close();
+  }
+}

package/src/core/gateway/rpc/error.ts

@@ -0,0 +1,11 @@
+// CANONICAL — single source of truth lives here. Do not duplicate. See packages/README.md.
+
+export class GatewayRpcError extends Error {
+  readonly code: string;
+
+  constructor(message: string, code = "gateway_error") {
+    super(message);
+    this.name = "GatewayRpcError";
+    this.code = code;
+  }
+}

package/src/core/gateway/rpc/index.ts

@@ -0,0 +1,5 @@
+export * from "./client.js";
+export * from "./device-crypto.js";
+export * from "./device-store.js";
+export * from "./error.js";
+export * from "./preauth-handshake.js";

package/src/core/gateway/rpc/preauth-handshake.ts

@@ -0,0 +1,99 @@
+// CANONICAL — single source of truth lives here. Do not duplicate. See packages/README.md.
+
+/**
+ * Keep token-only connect fallback strictly before the gateway pre-auth
+ * handshake timeout. Core owns the timing math; providers and host apps own
+ * gateway-specific env keys or explicit timeout overrides.
+ */
+export const DEFAULT_PREAUTH_HANDSHAKE_TIMEOUT_MS = 10_000;
+
+const HANDSHAKE_SAFETY_MARGIN_MS = 2_000;
+/** Leave at least this much room before the server closes the pre-auth window. */
+const MIN_MS_BEFORE_SERVER_CLOSE = 250;
+
+export type GatewayPreauthHandshakeEnv = Readonly<Record<string, string | undefined>>;
+
+export type GatewayPreauthHandshakeEnvKeys = Readonly<{
+  timeoutMs: string;
+  testTimeoutMs?: string;
+  testFlag?: string;
+}>;
+
+export const GATEWAY_PREAUTH_HANDSHAKE_ENV_KEYS: GatewayPreauthHandshakeEnvKeys = {
+  timeoutMs: "GATEWAY_PREAUTH_HANDSHAKE_TIMEOUT_MS",
+  testTimeoutMs: "GATEWAY_TEST_PREAUTH_HANDSHAKE_TIMEOUT_MS",
+  testFlag: "VITEST",
+};
+
+export type ResolvePreauthHandshakeTimeoutMsParams = {
+  env?: GatewayPreauthHandshakeEnv;
+  envKeys?: GatewayPreauthHandshakeEnvKeys;
+  preauthHandshakeTimeoutMs?: number;
+};
+
+type LegacyGatewayHandshakeEnv = Readonly<{
+  GATEWAY_PREAUTH_HANDSHAKE_TIMEOUT_MS?: string;
+  GATEWAY_TEST_PREAUTH_HANDSHAKE_TIMEOUT_MS?: string;
+  VITEST?: string;
+}>;
+
+function parsePositiveMs(value: string | undefined): number | null {
+  if (!value) {
+    return null;
+  }
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : null;
+}
+
+export function resolvePreauthHandshakeTimeoutMs(
+  params: ResolvePreauthHandshakeTimeoutMsParams = {},
+): number {
+  if (
+    typeof params.preauthHandshakeTimeoutMs === "number" &&
+    Number.isFinite(params.preauthHandshakeTimeoutMs) &&
+    params.preauthHandshakeTimeoutMs > 0
+  ) {
+    return params.preauthHandshakeTimeoutMs;
+  }
+  const env = params.env;
+  if (!env) {
+    return DEFAULT_PREAUTH_HANDSHAKE_TIMEOUT_MS;
+  }
+  const keys = params.envKeys ?? GATEWAY_PREAUTH_HANDSHAKE_ENV_KEYS;
+  const configuredTimeout = parsePositiveMs(env[keys.timeoutMs]);
+  if (configuredTimeout) return configuredTimeout;
+  const testFlag = keys.testFlag ? env[keys.testFlag] : undefined;
+  const testTimeout = keys.testTimeoutMs && testFlag
+    ? parsePositiveMs(env[keys.testTimeoutMs])
+    : null;
+  if (testTimeout) return testTimeout;
+  return DEFAULT_PREAUTH_HANDSHAKE_TIMEOUT_MS;
+}
+
+/**
+ * @deprecated Use resolvePreauthHandshakeTimeoutMs({ env }) with generic
+ * gateway env keys, or pass provider-specific env keys explicitly.
+ */
+export function resolvePreauthHandshakeTimeoutMsFromEnv(
+  env?: LegacyGatewayHandshakeEnv,
+): number {
+  return resolvePreauthHandshakeTimeoutMs({ env });
+}
+
+export type ResolveDeviceTokenOnlyFallbackMsParams = {
+  env?: GatewayPreauthHandshakeEnv;
+  envKeys?: GatewayPreauthHandshakeEnvKeys;
+  /** Explicit gateway handshake budget in milliseconds. */
+  preauthHandshakeTimeoutMs?: number;
+};
+
+/** Delay before sending `connect` without a nonce when device identity is enabled. */
+export function resolveDeviceTokenOnlyFallbackMs(
+  params?: ResolveDeviceTokenOnlyFallbackMsParams,
+): number {
+  const rawTimeout = resolvePreauthHandshakeTimeoutMs(params);
+
+  const preferred = Math.max(750, rawTimeout - HANDSHAKE_SAFETY_MARGIN_MS);
+  const maxAllowed = Math.max(1, rawTimeout - MIN_MS_BEFORE_SERVER_CLOSE);
+  return Math.min(preferred, maxAllowed);
+}

package/src/core/gateway/run/contracts.ts

@@ -0,0 +1,155 @@
+import type { GatewayResolvedRouteBinding } from "../../../contracts/team-manifest.js";
+
+export type AgentRunStatus = "active" | "idle" | "stalled" | "error";
+
+export type AgentRun = {
+  key: string;
+  title: string;
+  agentId: string;
+  channel: string;
+  updatedAt: number | null;
+  status: AgentRunStatus;
+  totalTokens: number;
+  errors: number;
+  /** Model used for this run (e.g. claude-sonnet-4, gpt-4). From backend when available. */
+  model?: string;
+  /** Cost in USD for this run. From backend when available. */
+  totalCostUsd?: number;
+  /** Optional manifest-derived binding for source/channel/team routing diagnostics. */
+  binding?: GatewayResolvedRouteBinding | null;
+};
+
+export type AgentRunPreviewItem = {
+  role: string;
+  text: string;
+  at: number | null;
+  eventType?: string;
+  toolName?: string;
+  durationMs?: number | null;
+  error?: string | null;
+};
+
+export type AgentRunDetailSnapshot = {
+  run: AgentRun | null;
+  preview: {
+    status: string;
+    items: AgentRunPreviewItem[];
+  };
+  usage: {
+    totalTokens: number;
+    totalCostUsd: number;
+    messages: number;
+    toolCalls: number;
+    errors: number;
+  };
+};
+
+/**
+ * Canonical wire names for live run-stream events.
+ *
+ * Producers (Hermes SSE, gateway WebSocket, run-preview poll stopgap, mock)
+ * MUST emit these exact strings on the `event` field of every
+ * {@link RunStreamEvent}. Consumers MUST switch on these constants — never
+ * inline string literals.
+ *
+ * Tool events are part of the contract even when the upstream transport does
+ * not yet emit them: the {@link RunPreviewPollProvider}-style implementation
+ * synthesizes them from {@link AgentRunPreviewItem} so the consumer code path
+ * is identical regardless of producer.
+ */
+export const RUN_STREAM_EVENT_NAMES = {
+  MESSAGE_DELTA: "message.delta",
+  RUN_COMPLETED: "run.completed",
+  RUN_FAILED: "run.failed",
+  RUN_CANCELLED: "run.cancelled",
+  APPROVAL_REQUEST: "approval.request",
+  TOOL_CALL_STARTED: "tool.call.started",
+  TOOL_CALL_COMPLETED: "tool.call.completed",
+  TOOL_CALL_FAILED: "tool.call.failed",
+} as const;
+
+export type RunStreamEventName =
+  (typeof RUN_STREAM_EVENT_NAMES)[keyof typeof RUN_STREAM_EVENT_NAMES];
+
+export type RunStreamToolStatus =
+  | "pending"
+  | "running"
+  | "completed"
+  | "failed";
+
+export type RunStreamToolCall = {
+  /** Stable id for this tool invocation within the run; producers should make this best-effort unique. */
+  id: string;
+  name: string;
+  status: RunStreamToolStatus;
+  /** Free-form provider-side event tag (e.g. the underlying SSE event name) for diagnostics. */
+  event?: string;
+  /** JSON-stringified arguments / input payload (size-bounded by producer). */
+  input?: string;
+  /** JSON-stringified result / output (size-bounded by producer). */
+  output?: string;
+  error?: string;
+  durationMs?: number;
+  /** Epoch ms when this snapshot was produced. */
+  at?: number;
+};
+
+export type RunStreamApprovalChoice = "once" | "session" | "always" | "deny";
+
+export type RunStreamMessageDeltaEvent = {
+  event: typeof RUN_STREAM_EVENT_NAMES.MESSAGE_DELTA;
+  runId: string;
+  delta: string;
+  at?: number;
+};
+
+export type RunStreamRunCompletedEvent = {
+  event: typeof RUN_STREAM_EVENT_NAMES.RUN_COMPLETED;
+  runId: string;
+  output?: string;
+  at?: number;
+};
+
+export type RunStreamRunFailedEvent = {
+  event: typeof RUN_STREAM_EVENT_NAMES.RUN_FAILED;
+  runId: string;
+  error: string;
+  at?: number;
+};
+
+export type RunStreamRunCancelledEvent = {
+  event: typeof RUN_STREAM_EVENT_NAMES.RUN_CANCELLED;
+  runId: string;
+  reason?: string;
+  at?: number;
+};
+
+export type RunStreamApprovalRequestEvent = {
+  event: typeof RUN_STREAM_EVENT_NAMES.APPROVAL_REQUEST;
+  runId: string;
+  choices: RunStreamApprovalChoice[];
+  at?: number;
+};
+
+export type RunStreamToolEvent = {
+  event:
+    | typeof RUN_STREAM_EVENT_NAMES.TOOL_CALL_STARTED
+    | typeof RUN_STREAM_EVENT_NAMES.TOOL_CALL_COMPLETED
+    | typeof RUN_STREAM_EVENT_NAMES.TOOL_CALL_FAILED;
+  runId: string;
+  toolCall: RunStreamToolCall;
+  at?: number;
+};
+
+/**
+ * Discriminated union of every event a {@link RunEventStreamProvider}-shaped
+ * source can emit. Add new variants here when extending the contract — do not
+ * add untagged variants.
+ */
+export type RunStreamEvent =
+  | RunStreamMessageDeltaEvent
+  | RunStreamRunCompletedEvent
+  | RunStreamRunFailedEvent
+  | RunStreamRunCancelledEvent
+  | RunStreamApprovalRequestEvent
+  | RunStreamToolEvent;