@elizaos/plugin-elizacloud 2.0.0-alpha.7 → 2.0.0-beta.1

package/src/lib/config-env.ts

@@ -0,0 +1,168 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { resolveStateDir } from "./state-paths";
+
+const CONFIG_ENV_FILENAME = "config.env";
+const BAK_SUFFIX = ".bak";
+const TMP_SUFFIX = ".tmp";
+const KEY_PATTERN = /^[A-Z][A-Z0-9_]*$/;
+
+const BLOCKED_CONFIG_ENV_KEYS: ReadonlySet<string> = new Set([
+  "NODE_OPTIONS",
+  "NODE_EXTRA_CA_CERTS",
+  "NODE_TLS_REJECT_UNAUTHORIZED",
+  "NODE_PATH",
+  "LD_PRELOAD",
+  "LD_LIBRARY_PATH",
+  "DYLD_INSERT_LIBRARIES",
+  "DYLD_LIBRARY_PATH",
+  "DYLD_FRAMEWORK_PATH",
+  "DYLD_FALLBACK_FRAMEWORK_PATH",
+  "DYLD_FALLBACK_LIBRARY_PATH",
+  "PATH",
+  "HOME",
+  "SHELL",
+  "HTTP_PROXY",
+  "HTTPS_PROXY",
+  "ALL_PROXY",
+  "NO_PROXY",
+  "SSL_CERT_FILE",
+  "SSL_CERT_DIR",
+  "CURL_CA_BUNDLE",
+]);
+
+export interface PersistConfigEnvOptions {
+  stateDir?: string;
+}
+
+interface ParsedConfigEnv {
+  lines: string[];
+  index: Map<string, number>;
+}
+
+function parseConfigEnv(contents: string): ParsedConfigEnv {
+  const lines = contents.length === 0 ? [] : contents.split(/\r?\n/);
+  if (lines.length > 0 && lines[lines.length - 1] === "") {
+    lines.pop();
+  }
+  const index = new Map<string, number>();
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i] ?? "";
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const eq = line.indexOf("=");
+    if (eq <= 0) continue;
+    const key = line.slice(0, eq).trim();
+    if (KEY_PATTERN.test(key)) index.set(key, i);
+  }
+  return { lines, index };
+}
+
+function serialiseConfigEnv(parsed: ParsedConfigEnv): string {
+  return parsed.lines.length === 0 ? "" : `${parsed.lines.join("\n")}\n`;
+}
+
+function encodeValue(value: string): string {
+  if (value === "") return "";
+  const needsQuoting = /[\s#"'\\]|^\s|\s$/.test(value) || /\n|\r/.test(value);
+  if (!needsQuoting) return value;
+  const escaped = value
+    .replace(/\\/g, "\\\\")
+    .replace(/"/g, '\\"')
+    .replace(/\n/g, "\\n")
+    .replace(/\r/g, "\\r");
+  return `"${escaped}"`;
+}
+
+function validateKey(key: string): void {
+  if (!KEY_PATTERN.test(key)) {
+    throw new Error(
+      `persistConfigEnv: invalid key "${key}" - must match /^[A-Z][A-Z0-9_]*$/`,
+    );
+  }
+  if (BLOCKED_CONFIG_ENV_KEYS.has(key)) {
+    throw new Error(
+      `persistConfigEnv: key "${key}" is a shell/runtime hijack vector and cannot be written`,
+    );
+  }
+}
+
+async function readIfExists(filePath: string): Promise<string | null> {
+  try {
+    return await fs.readFile(filePath, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+async function writeAtomic(filePath: string, contents: string): Promise<void> {
+  const tmpPath = `${filePath}${TMP_SUFFIX}`;
+  const handle = await fs.open(tmpPath, "w", 0o600);
+  try {
+    await handle.writeFile(contents, "utf8");
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+  await fs.rename(tmpPath, filePath);
+}
+
+let writeChain: Promise<unknown> = Promise.resolve();
+
+function serialise<T>(fn: () => Promise<T>): Promise<T> {
+  const next = writeChain.then(fn, fn);
+  writeChain = next.catch(() => undefined);
+  return next;
+}
+
+function resolveConfigEnvPath(stateDir?: string): string {
+  return path.join(stateDir ?? resolveStateDir(), CONFIG_ENV_FILENAME);
+}
+
+export async function persistConfigEnv(
+  key: string,
+  value: string,
+  opts: PersistConfigEnvOptions = {},
+): Promise<void> {
+  validateKey(key);
+
+  await serialise(async () => {
+    const filePath = resolveConfigEnvPath(opts.stateDir);
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+
+    const existing = (await readIfExists(filePath)) ?? "";
+    const parsed = parseConfigEnv(existing);
+    const existingIdx = parsed.index.get(key);
+    const isDelete = value === "";
+
+    if (isDelete) {
+      if (existingIdx === undefined) {
+        delete process.env[key];
+        return;
+      }
+      parsed.lines.splice(existingIdx, 1);
+    } else {
+      const encoded = `${key}=${encodeValue(value)}`;
+      if (existingIdx === undefined) {
+        parsed.lines.push(encoded);
+      } else {
+        parsed.lines[existingIdx] = encoded;
+      }
+    }
+
+    if (existing.length > 0) {
+      await fs.writeFile(`${filePath}${BAK_SUFFIX}`, existing, {
+        encoding: "utf8",
+        mode: 0o600,
+      });
+    }
+
+    await writeAtomic(filePath, serialiseConfigEnv(parsed));
+    if (isDelete) {
+      delete process.env[key];
+    } else {
+      process.env[key] = value;
+    }
+  });
+}

package/src/lib/config-like.ts

@@ -0,0 +1,149 @@
+import type {
+  DeploymentTargetConfig,
+  LinkedAccountFlagsConfig,
+  ServiceCapability,
+  ServiceRoutingConfig,
+} from "@elizaos/core";
+
+export interface CloudProxyConfigLike {
+  cloud?: {
+    apiKey?: string;
+    baseUrl?: string;
+    enabled?: boolean;
+    serviceKey?: string;
+    backup?: {
+      autoBackupIntervalMs?: number;
+    };
+    bridge?: {
+      heartbeatIntervalMs?: number;
+    };
+  };
+}
+
+export type CloudConfig = NonNullable<CloudProxyConfigLike["cloud"]>;
+
+export type ElizaConfig = Record<string, unknown> &
+  CloudProxyConfigLike & {
+    deploymentTarget?: DeploymentTargetConfig;
+    linkedAccounts?: LinkedAccountFlagsConfig;
+    serviceRouting?: ServiceRoutingConfig;
+  };
+
+export interface AutonomousConfigLike {
+  [key: string]: unknown;
+}
+
+type MutableElizaConfig = Partial<ElizaConfig> & {
+  cloud?: Record<string, unknown>;
+  deploymentTarget?: DeploymentTargetConfig;
+  linkedAccounts?: LinkedAccountFlagsConfig;
+  serviceRouting?: ServiceRoutingConfig;
+};
+
+function ensureLinkedAccounts(
+  config: MutableElizaConfig,
+): LinkedAccountFlagsConfig {
+  config.linkedAccounts ??= {};
+  return config.linkedAccounts;
+}
+
+function ensureServiceRouting(
+  config: MutableElizaConfig,
+): ServiceRoutingConfig {
+  config.serviceRouting ??= {};
+  return config.serviceRouting;
+}
+
+function persistDeploymentTarget(
+  config: MutableElizaConfig,
+  deploymentTarget: DeploymentTargetConfig | null | undefined,
+): void {
+  if (!deploymentTarget) {
+    delete config.deploymentTarget;
+    return;
+  }
+  config.deploymentTarget = { ...deploymentTarget };
+}
+
+function persistLinkedAccounts(
+  config: MutableElizaConfig,
+  linkedAccounts: LinkedAccountFlagsConfig | null | undefined,
+): void {
+  if (!linkedAccounts) return;
+
+  const existing = ensureLinkedAccounts(config);
+  for (const [accountId, account] of Object.entries(linkedAccounts)) {
+    if (!account || Object.keys(account).length === 0) {
+      delete existing[accountId];
+      continue;
+    }
+    existing[accountId] = {
+      ...existing[accountId],
+      ...account,
+    };
+  }
+
+  if (Object.keys(existing).length === 0) {
+    delete config.linkedAccounts;
+  }
+}
+
+function persistServiceRouting(
+  config: MutableElizaConfig,
+  serviceRouting: ServiceRoutingConfig | null | undefined,
+  clearRoutes: readonly ServiceCapability[] = [],
+): void {
+  const existing = ensureServiceRouting(config);
+
+  for (const capability of clearRoutes) {
+    delete existing[capability];
+  }
+
+  if (serviceRouting) {
+    for (const [capability, route] of Object.entries(serviceRouting)) {
+      const serviceKey = capability as ServiceCapability;
+      if (!route || Object.keys(route).length === 0) {
+        delete existing[serviceKey];
+        continue;
+      }
+      existing[serviceKey] = { ...route };
+    }
+  }
+
+  if (Object.keys(existing).length === 0) {
+    delete config.serviceRouting;
+  }
+}
+
+export function applyCanonicalOnboardingConfig(
+  config: MutableElizaConfig,
+  args: {
+    deploymentTarget?: DeploymentTargetConfig | null;
+    linkedAccounts?: LinkedAccountFlagsConfig | null;
+    serviceRouting?: ServiceRoutingConfig | null;
+    clearRoutes?: readonly ServiceCapability[];
+  },
+): void {
+  if (args.deploymentTarget !== undefined) {
+    persistDeploymentTarget(config, args.deploymentTarget);
+  }
+  if (args.linkedAccounts !== undefined) {
+    persistLinkedAccounts(config, args.linkedAccounts);
+  }
+  if (args.serviceRouting !== undefined || args.clearRoutes?.length) {
+    persistServiceRouting(config, args.serviceRouting, args.clearRoutes);
+  }
+}
+
+export function normalizeEnvValue(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return trimmed || undefined;
+}
+
+export function isTimeoutError(error: unknown): boolean {
+  if (!(error instanceof Error)) return false;
+  if (error.name === "TimeoutError" || error.name === "AbortError") return true;
+  const message = error.message.toLowerCase();
+  return message.includes("timed out") || message.includes("timeout");
+}

package/src/lib/credential-type-map.ts

@@ -0,0 +1,130 @@
+/**
+ * Mapping from workflow-plugin credential type names → Eliza Cloud connector slugs.
+ *
+ * The workflow plugin's LLM emits credential type strings (e.g. `gmailOAuth2`,
+ * `slackOAuth2Api`) on each node that needs an external account. The cloud
+ * exposes per-connector OAuth flows under `/api/v1/eliza/<connector>/...`.
+ *
+ * This map is the single source of truth for which workflow credential type
+ * resolves through which cloud connector + with which OAuth scopes. Add new
+ * entries when the cloud gains support for additional connectors; do not
+ * scatter cred-type → connector logic elsewhere.
+ *
+ * Cloud-side endpoint convention (see cloud/apps/api/v1/eliza/<connector>/):
+ *   POST /api/v1/eliza/<connector>/connect/initiate     → { authUrl }
+ *   GET  /api/v1/eliza/<connector>/status               → { connected, ... }
+ *
+ * Not every connector below has a fully-implemented cloud endpoint yet — the
+ * provider returns `null` for unmapped types and `needs_auth` (with the
+ * cloud-issued OAuth URL) for mapped-but-not-connected accounts. See
+ * `cloud-credential-provider.ts` for the resolution logic.
+ */
+
+export interface CredentialTypeMapping {
+  /**
+   * Cloud connector slug used in the URL path
+   * (`/api/v1/eliza/<connector>/connect/initiate`).
+   */
+  connector: string;
+  /**
+   * Optional capability tokens passed to the cloud's `connect/initiate`
+   * endpoint. The cloud translates these to provider-specific OAuth scopes
+   * (e.g. Google's `google.gmail.send` → `https://www.googleapis.com/auth/gmail.send`).
+   */
+  capabilities?: string[];
+  /**
+   * Friendly description used in `needs_auth` UI prompts. The runtime may
+   * surface this verbatim to the end-user.
+   */
+  friendlyName: string;
+}
+
+/**
+ * Workflow credential type → cloud connector mapping.
+ *
+ * Names mirror the n8n / workflows-plugin convention used by the LLM in
+ * `plugins/plugin-workflow/src/utils/workflow-prompts/workflowGeneration.ts`.
+ * Both `gmailOAuth2` and `gmailOAuth2Api` map to the same connector — the
+ * workflow resolver does fuzzy `Api`-suffix matching upstream, but we keep
+ * both keys here so `checkCredentialTypes` answers truthfully without the
+ * caller having to know about that fuzziness.
+ */
+export const credTypeToConnector: ReadonlyMap<string, CredentialTypeMapping> = new Map([
+  // ─── Google ──────────────────────────────────────────────────────────
+  // Cloud endpoint: /api/v1/eliza/google/{connect/initiate,status,disconnect}
+  // The cloud's capability tokens are documented in
+  // cloud/apps/api/v1/eliza/google/connect/initiate/route.ts.
+  [
+    "gmailOAuth2",
+    {
+      connector: "google",
+      capabilities: ["google.gmail.triage", "google.gmail.send", "google.gmail.manage"],
+      friendlyName: "Gmail",
+    },
+  ],
+  [
+    "gmailOAuth2Api",
+    {
+      connector: "google",
+      capabilities: ["google.gmail.triage", "google.gmail.send", "google.gmail.manage"],
+      friendlyName: "Gmail",
+    },
+  ],
+  [
+    "googleCalendarOAuth2Api",
+    {
+      connector: "google",
+      capabilities: ["google.calendar.read", "google.calendar.write"],
+      friendlyName: "Google Calendar",
+    },
+  ],
+  [
+    "googleSheetsOAuth2Api",
+    {
+      connector: "google",
+      capabilities: ["google.basic_identity"],
+      friendlyName: "Google Sheets",
+    },
+  ],
+
+  // ─── GitHub ──────────────────────────────────────────────────────────
+  // Cloud endpoint: /api/v1/eliza/github-oauth-complete/ (callback only).
+  // The initiate flow is host-driven; the provider returns `needs_auth`
+  // pointing at the cloud's GitHub install URL when not connected.
+  [
+    "githubOAuth2Api",
+    {
+      connector: "github",
+      friendlyName: "GitHub",
+    },
+  ],
+  [
+    "githubApi",
+    {
+      connector: "github",
+      friendlyName: "GitHub",
+    },
+  ],
+
+  // ─── Discord ─────────────────────────────────────────────────────────
+  // Cloud endpoint: /api/v1/eliza/discord/gateway-agent/ (gateway pairing).
+  // No OAuth-token-issuance flow yet — provider returns `null` so the
+  // workflow resolver falls back to its default missing-connection report.
+  [
+    "discordApi",
+    {
+      connector: "discord",
+      friendlyName: "Discord",
+    },
+  ],
+  [
+    "discordBotApi",
+    {
+      connector: "discord",
+      friendlyName: "Discord (Bot)",
+    },
+  ],
+]);
+
+/** Set used by `checkCredentialTypes` for O(1) supported-set membership. */
+export const supportedCredTypes: ReadonlySet<string> = new Set(credTypeToConnector.keys());

package/src/lib/feature-flags.ts

@@ -0,0 +1,26 @@
+function readBoolFlag(name: string, fallback = false): boolean {
+  const raw = process.env[name];
+  if (raw === undefined || raw === null || raw === "") return fallback;
+  const trimmed = String(raw).trim().toLowerCase();
+  if (
+    trimmed === "1" ||
+    trimmed === "true" ||
+    trimmed === "yes" ||
+    trimmed === "on"
+  ) {
+    return true;
+  }
+  if (
+    trimmed === "0" ||
+    trimmed === "false" ||
+    trimmed === "no" ||
+    trimmed === "off"
+  ) {
+    return false;
+  }
+  return fallback;
+}
+
+export function isCloudWalletEnabled(): boolean {
+  return readBoolFlag("ENABLE_CLOUD_WALLET");
+}

package/src/lib/http.ts

@@ -0,0 +1,139 @@
+import type http from "node:http";
+
+export interface ReadJsonBodyOptions {
+  maxBytes?: number;
+  tooLargeMessage?: string;
+  destroyOnTooLarge?: boolean;
+  requireObject?: boolean;
+}
+
+export interface RouteRequestMeta {
+  req: http.IncomingMessage;
+  res: http.ServerResponse;
+  method: string;
+  pathname: string;
+}
+
+export interface RouteHelpers {
+  json: (res: http.ServerResponse, data: unknown, status?: number) => void;
+  error: (res: http.ServerResponse, message: string, status?: number) => void;
+  readJsonBody: <T extends object>(
+    req: http.IncomingMessage,
+    res: http.ServerResponse,
+    options?: ReadJsonBodyOptions,
+  ) => Promise<T | null>;
+}
+
+function scrubStackFields(value: unknown): unknown {
+  if (value instanceof Error) {
+    return { error: value.message || "Internal error" };
+  }
+  if (Array.isArray(value)) {
+    return value.map(scrubStackFields);
+  }
+  if (value && typeof value === "object") {
+    const out: Record<string, unknown> = {};
+    for (const [key, nested] of Object.entries(value)) {
+      if (key === "stack" || key === "stackTrace") continue;
+      out[key] = scrubStackFields(nested);
+    }
+    return out;
+  }
+  return value;
+}
+
+export function sendJson(
+  res: http.ServerResponse,
+  body: unknown,
+  status = 200,
+): void {
+  if (res.headersSent) return;
+  res.statusCode = status;
+  res.setHeader("content-type", "application/json; charset=utf-8");
+  res.end(JSON.stringify(scrubStackFields(body)));
+}
+
+export function sendJsonError(
+  res: http.ServerResponse,
+  message: string,
+  status = 400,
+): void {
+  sendJson(res, { error: message }, status);
+}
+
+async function readRequestBody(
+  req: http.IncomingMessage,
+  options: ReadJsonBodyOptions,
+): Promise<string | null> {
+  const maxBytes = options.maxBytes ?? 1_048_576;
+  const chunks: Buffer[] = [];
+  let size = 0;
+
+  for await (const chunk of req) {
+    const buffer = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+    size += buffer.length;
+    if (size > maxBytes) {
+      if (options.destroyOnTooLarge) req.destroy();
+      throw new Error(options.tooLargeMessage ?? "Request body too large");
+    }
+    chunks.push(buffer);
+  }
+
+  if (chunks.length === 0) return null;
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+export async function readJsonBody<T extends object = Record<string, unknown>>(
+  req: http.IncomingMessage,
+  res: http.ServerResponse,
+  options: ReadJsonBodyOptions = {},
+): Promise<T | null> {
+  const cached = (req as http.IncomingMessage & { body?: unknown }).body;
+  if (cached !== undefined) {
+    if (
+      options.requireObject !== false &&
+      (!cached || typeof cached !== "object" || Array.isArray(cached))
+    ) {
+      sendJsonError(res, "Request body must be a JSON object", 400);
+      return null;
+    }
+    return cached as T;
+  }
+
+  let raw: string | null;
+  try {
+    raw = await readRequestBody(req, options);
+  } catch (error) {
+    sendJsonError(
+      res,
+      error instanceof Error ? error.message : "Failed to read request body",
+      413,
+    );
+    return null;
+  }
+
+  if (!raw?.trim()) {
+    const empty = {} as T;
+    (req as http.IncomingMessage & { body?: unknown }).body = empty;
+    return empty;
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    sendJsonError(res, "Invalid JSON in request body", 400);
+    return null;
+  }
+
+  if (
+    options.requireObject !== false &&
+    (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+  ) {
+    sendJsonError(res, "Request body must be a JSON object", 400);
+    return null;
+  }
+
+  (req as http.IncomingMessage & { body?: unknown }).body = parsed;
+  return parsed as T;
+}