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

package/src/cloud/validate-url.ts

@@ -0,0 +1,181 @@
+import dns from "node:dns";
+import net from "node:net";
+import { promisify } from "node:util";
+
+const dnsLookupAll = promisify(dns.lookup);
+
+const BLOCKED_IPV4_CIDRS: Array<{ base: number; mask: number }> = [
+  cidrV4("0.0.0.0", 8),
+  cidrV4("10.0.0.0", 8),
+  cidrV4("172.16.0.0", 12),
+  cidrV4("192.168.0.0", 16),
+  cidrV4("100.64.0.0", 10),
+  cidrV4("127.0.0.0", 8),
+  cidrV4("169.254.0.0", 16),
+  cidrV4("192.0.0.0", 24),
+  cidrV4("198.18.0.0", 15),
+  cidrV4("192.0.2.0", 24),
+  cidrV4("198.51.100.0", 24),
+  cidrV4("203.0.113.0", 24),
+  cidrV4("224.0.0.0", 4),
+  cidrV4("240.0.0.0", 4),
+];
+
+function normalizeHostLike(value: string): string {
+  return value
+    .trim()
+    .toLowerCase()
+    .replace(/^\[|\]$/g, "");
+}
+
+function decodeIpv6MappedHex(mapped: string): string | null {
+  const parts = mapped.split(":");
+  if (parts.length < 1 || parts.length > 2) return null;
+
+  const parsed = parts.map((part) => {
+    if (!/^[0-9a-f]{1,4}$/i.test(part)) return Number.NaN;
+    return Number.parseInt(part, 16);
+  });
+  if (parsed.some((value) => !Number.isFinite(value))) return null;
+
+  const [hi, lo] = parsed.length === 1 ? [0, parsed[0]] : parsed;
+  const octets = [hi >> 8, hi & 0xff, lo >> 8, lo & 0xff];
+  return octets.join(".");
+}
+
+function canonicalizeIpv6(ip: string): string | null {
+  try {
+    return new URL(`http://[${ip}]/`).hostname.replace(/^\[|\]$/g, "");
+  } catch {
+    return null;
+  }
+}
+
+function normalizeIpForPolicy(ip: string): string {
+  const base = normalizeHostLike(ip).split("%")[0];
+  if (!base) return base;
+
+  let normalized = base;
+  if (net.isIP(normalized) === 6) {
+    normalized = canonicalizeIpv6(normalized) ?? normalized;
+  }
+
+  let mapped: string | null = null;
+  if (normalized.startsWith("::ffff:")) {
+    mapped = normalized.slice("::ffff:".length);
+  } else if (normalized.startsWith("0:0:0:0:0:ffff:")) {
+    mapped = normalized.slice("0:0:0:0:0:ffff:".length);
+  }
+  if (!mapped) return normalized;
+
+  if (net.isIP(mapped) === 4) return mapped;
+  return decodeIpv6MappedHex(mapped) ?? normalized;
+}
+
+function cidrV4(base: string, prefix: number): { base: number; mask: number } {
+  const parsed = parseIpv4ToInt(base);
+  if (parsed === null) {
+    throw new Error(`Invalid CIDR base IPv4 address: ${base}`);
+  }
+  const shift = 32 - prefix;
+  const mask = shift === 32 ? 0 : (0xffffffff << shift) >>> 0;
+  return { base: parsed & mask, mask };
+}
+
+function parseIpv4ToInt(ip: string): number | null {
+  const parts = ip.split(".");
+  if (parts.length !== 4) return null;
+
+  let value = 0;
+  for (const part of parts) {
+    if (!/^\d{1,3}$/.test(part)) return null;
+    const octet = Number.parseInt(part, 10);
+    if (!Number.isInteger(octet) || octet < 0 || octet > 255) return null;
+    value = (value << 8) | octet;
+  }
+
+  return value >>> 0;
+}
+
+function isBlockedIpv4(ip: string): boolean {
+  const asInt = parseIpv4ToInt(ip);
+  if (asInt === null) return true;
+  return BLOCKED_IPV4_CIDRS.some((cidr) => (asInt & cidr.mask) === cidr.base);
+}
+
+function isBlockedIpv6(ip: string): boolean {
+  const normalized = ip.toLowerCase();
+  return (
+    normalized === "::" ||
+    normalized === "::1" ||
+    /^fe[89ab][0-9a-f]:/.test(normalized) ||
+    /^f[cd][0-9a-f]{2}:/i.test(normalized) ||
+    normalized.startsWith("ff")
+  );
+}
+
+function isBlockedIp(ip: string): boolean {
+  const normalized = normalizeIpForPolicy(ip);
+  const family = net.isIP(normalized);
+  if (family === 4) return isBlockedIpv4(normalized);
+  if (family === 6) return isBlockedIpv6(normalized);
+  return false;
+}
+
+export async function validateCloudBaseUrl(
+  rawUrl: string,
+): Promise<string | null> {
+  let parsed: URL;
+  try {
+    parsed = new URL(rawUrl);
+  } catch {
+    return `Invalid cloud base URL: "${rawUrl}"`;
+  }
+
+  if (parsed.protocol !== "https:") {
+    return `Cloud base URL must use HTTPS, got "${parsed.protocol}" in "${rawUrl}"`;
+  }
+
+  const hostname = normalizeHostLike(parsed.hostname);
+  if (!hostname) {
+    return `Invalid cloud base URL: "${rawUrl}"`;
+  }
+
+  if (
+    hostname === "localhost" ||
+    hostname.endsWith(".localhost") ||
+    hostname.endsWith(".local")
+  ) {
+    return `Cloud base URL "${rawUrl}" points to a blocked local hostname.`;
+  }
+
+  // Dev-mode bypass: skip IP-range blocking but keep URL format checks above.
+  if (process.env.NODE_ENV === "development" || process.env.ELIZA_DEV) {
+    return null;
+  }
+
+  if (isBlockedIp(hostname)) {
+    return `Cloud base URL "${rawUrl}" points to a blocked address.`;
+  }
+
+  try {
+    const results = await dnsLookupAll(hostname, { all: true });
+    const addresses = Array.isArray(results) ? results : [results];
+    for (const entry of addresses) {
+      const ip =
+        typeof entry === "string"
+          ? entry
+          : (entry as { address: string }).address;
+      if (isBlockedIp(ip)) {
+        return (
+          `Cloud base URL "${rawUrl}" resolves to ${ip}, ` +
+          "which is a blocked internal/metadata address."
+        );
+      }
+    }
+  } catch {
+    return `Cloud base URL "${rawUrl}" could not be resolved via DNS.`;
+  }
+
+  return null;
+}

package/src/cloud-providers/cloud-status.ts

@@ -0,0 +1,75 @@
+/**
+ * cloudStatusProvider — Container and connection status in agent state.
+ */
+
+import type { IAgentRuntime, Memory, Provider, ProviderResult, State } from "@elizaos/core";
+import type { CloudAuthService } from "../services/cloud-auth";
+import type { CloudBridgeService } from "../services/cloud-bridge";
+import type { CloudContainerService } from "../services/cloud-container";
+
+const MAX_CONTAINER_SUMMARIES = 10;
+
+export const cloudStatusProvider: Provider = {
+  name: "elizacloud_status",
+  description: "ElizaCloud container and connection status",
+  descriptionCompressed: "ElizaCloud container/connection status.",
+  dynamic: true,
+  position: 90,
+  contexts: ["settings", "finance"],
+  contextGate: { anyOf: ["settings", "finance"] },
+  cacheStable: false,
+  cacheScope: "turn",
+  async get(runtime: IAgentRuntime, _message: Memory, _state: State): Promise<ProviderResult> {
+    try {
+      const auth = runtime.getService("CLOUD_AUTH") as CloudAuthService | undefined;
+      if (!auth?.isAuthenticated()) {
+        return {
+          text: "ElizaCloud: Not authenticated",
+          values: { cloudAuthenticated: false },
+        };
+      }
+
+      const containerSvc = runtime.getService("CLOUD_CONTAINER") as
+        | CloudContainerService
+        | undefined;
+      const bridgeSvc = runtime.getService("CLOUD_BRIDGE") as CloudBridgeService | undefined;
+      const containers = containerSvc?.getTrackedContainers() ?? [];
+      const connected = bridgeSvc?.getConnectedContainerIds() ?? [];
+
+      const running = containers.filter((c) => c.status === "running").length;
+      const deploying = containers.filter(
+        (c) => c.status === "pending" || c.status === "building" || c.status === "deploying"
+      ).length;
+
+      const summaries = containers.slice(0, MAX_CONTAINER_SUMMARIES).map((c) => ({
+        id: c.id,
+        name: c.name,
+        status: c.status,
+        url: c.load_balancer_url,
+        billing: c.billing_status,
+        bridged: connected.includes(c.id),
+      }));
+
+      const lines = [
+        `ElizaCloud: ${containers.length} container(s), ${running} running, ${connected.length} bridged`,
+        ...summaries.map(
+          (c) =>
+            `  - ${c.name} [${c.status}]${c.url ? ` @ ${c.url}` : ""}${c.bridged ? " (bridged)" : ""}`
+        ),
+      ];
+
+      return {
+        text: lines.join("\n"),
+        values: {
+          cloudAuthenticated: true,
+          totalContainers: containers.length,
+          runningContainers: running,
+          deployingContainers: deploying,
+        },
+        data: { containers: summaries, truncated: containers.length > summaries.length },
+      };
+    } catch {
+      return { text: "", values: {}, data: {} };
+    }
+  },
+};

package/src/cloud-providers/container-health.ts

@@ -0,0 +1,68 @@
+/**
+ * containerHealthProvider — Container health in agent state (private, on-demand).
+ */
+
+import type { IAgentRuntime, Memory, Provider, ProviderResult, State } from "@elizaos/core";
+import type { CloudAuthService } from "../services/cloud-auth";
+import type { CloudContainerService } from "../services/cloud-container";
+
+const MAX_HEALTH_REPORTS = 10;
+
+export const containerHealthProvider: Provider = {
+  name: "elizacloud_health",
+  description: "ElizaCloud container health",
+  descriptionCompressed: "ElizaCloud container health.",
+  dynamic: true,
+  position: 92,
+  private: true,
+  contexts: ["settings", "finance"],
+  contextGate: { anyOf: ["settings", "finance"] },
+  cacheStable: false,
+  cacheScope: "turn",
+  async get(runtime: IAgentRuntime, _message: Memory, _state: State): Promise<ProviderResult> {
+    try {
+      const auth = runtime.getService("CLOUD_AUTH") as CloudAuthService | undefined;
+      if (!auth?.isAuthenticated()) return { text: "" };
+
+      const svc = runtime.getService("CLOUD_CONTAINER") as CloudContainerService | undefined;
+      const running = svc?.getTrackedContainers().filter((c) => c.status === "running") ?? [];
+      if (running.length === 0)
+        return {
+          text: "No running containers.",
+          values: { healthyContainers: 0 },
+        };
+
+      // NOTE: True health would require hitting each container's health_check_path
+      // endpoint over the network.  We approximate here using locally-cached state:
+      // a container is considered healthy when it is running, billing is active,
+      // and there is no recorded error message.
+      const reports = running.slice(0, MAX_HEALTH_REPORTS).map((c) => ({
+        id: c.id,
+        name: c.name,
+        healthy: c.status === "running" && c.billing_status === "active" && !c.error_message,
+        status: c.status,
+        billing: c.billing_status,
+      }));
+
+      const healthy = reports.filter((r) => r.healthy).length;
+      const text = [
+        `Health: ${healthy}/${reports.length} healthy`,
+        ...reports.map(
+          (r) =>
+            `  - ${r.name}: ${r.healthy ? "OK" : "UNHEALTHY"} (status=${r.status}, billing=${r.billing})`
+        ),
+      ].join("\n");
+
+      return {
+        text,
+        values: {
+          healthyContainers: healthy,
+          unhealthyContainers: reports.length - healthy,
+        },
+        data: { reports, truncated: running.length > reports.length },
+      };
+    } catch {
+      return { text: "", values: {}, data: {} };
+    }
+  },
+};

package/src/cloud-providers/credit-balance.ts

@@ -0,0 +1,70 @@
+/** Credit balance in agent state (60s cache). */
+
+import type { IAgentRuntime, Memory, Provider, ProviderResult, State } from "@elizaos/core";
+import { logger } from "@elizaos/core";
+import type { CloudAuthService } from "../services/cloud-auth";
+import type { CreditBalanceResponse } from "../types/cloud";
+
+const TOP_UP_URL = "https://www.elizacloud.ai/dashboard/settings?tab=billing";
+const creditCaches = new WeakMap<IAgentRuntime, { value: number; at: number }>();
+const TTL = 60_000;
+const MAX_CREDIT_TEXT_CHARS = 240;
+
+export const creditBalanceProvider: Provider = {
+  name: "elizacloud_credits",
+  description: "ElizaCloud credit balance",
+  descriptionCompressed: "ElizaCloud credit balance.",
+  dynamic: true,
+  contexts: ["settings", "finance"],
+  contextGate: { anyOf: ["settings", "finance"] },
+  cacheStable: false,
+  cacheScope: "turn",
+  position: 91,
+  async get(runtime: IAgentRuntime, _message: Memory, _state: State): Promise<ProviderResult> {
+    const auth = runtime.getService("CLOUD_AUTH") as CloudAuthService | undefined;
+    if (!auth?.isAuthenticated()) return { text: "" };
+
+    const cached = creditCaches.get(runtime);
+    if (cached && Date.now() - cached.at < TTL) {
+      const result = format(cached.value);
+      return { ...result, text: (result.text ?? "").slice(0, MAX_CREDIT_TEXT_CHARS) };
+    }
+
+    let balance: number;
+    try {
+      const { data } = await auth.getClient().get<CreditBalanceResponse>("/credits/balance");
+      balance = data.balance;
+    } catch (err) {
+      logger.warn(
+        `[CloudCredits] Failed to fetch balance: ${err instanceof Error ? err.message : err}`
+      );
+      if (cached) {
+        const result = format(cached.value);
+        return { ...result, text: (result.text ?? "").slice(0, MAX_CREDIT_TEXT_CHARS) };
+      }
+      return { text: "", values: { cloudCreditsUnavailable: true }, data: {} };
+    }
+    creditCaches.set(runtime, { value: balance, at: Date.now() });
+
+    if (balance < 1.0) logger.warn(`[CloudCredits] Low balance: $${balance.toFixed(2)}`);
+    const result = format(balance);
+    return { ...result, text: (result.text ?? "").slice(0, MAX_CREDIT_TEXT_CHARS) };
+  },
+};
+
+function format(balance: number): ProviderResult {
+  const low = balance < 2.0;
+  const critical = balance < 0.5;
+  let text = `ElizaCloud credits: $${balance.toFixed(2)}`;
+  if (critical) text += ` (CRITICAL — top up at ${TOP_UP_URL})`;
+  else if (low) text += ` (LOW — top up at ${TOP_UP_URL})`;
+  return {
+    text,
+    values: {
+      cloudCredits: balance,
+      cloudCreditsLow: low,
+      cloudCreditsCritical: critical,
+      cloudTopUpUrl: TOP_UP_URL,
+    },
+  };
+}

package/src/cloud-providers/index.ts

@@ -0,0 +1,3 @@
+export { cloudStatusProvider } from "./cloud-status";
+export { containerHealthProvider } from "./container-health";
+export { creditBalanceProvider } from "./credit-balance";

package/src/cloud-providers/model-registry.ts

@@ -0,0 +1,74 @@
+/** Exposes available cloud models in agent state. */
+
+import type { IAgentRuntime, Memory, Provider, ProviderResult, State } from "@elizaos/core";
+import type { CloudModelRegistryService, ModelsByProvider } from "../services/cloud-model-registry";
+
+const TTL = 300_000; // 5 minutes
+const MAX_MODEL_PROVIDERS = 12;
+const MAX_MODELS_PER_PROVIDER = 50;
+
+/**
+ * Per-runtime cache using a WeakMap keyed by the runtime object.
+ * This avoids sharing stale model data between different agent instances
+ * running in the same process.
+ */
+const runtimeCaches = new WeakMap<IAgentRuntime, { value: ModelsByProvider; at: number }>();
+
+export const modelRegistryProvider: Provider = {
+  name: "elizacloud_models",
+  description: "Available AI models from ElizaCloud grouped by provider",
+  descriptionCompressed: "Available AI models from ElizaCloud by provider.",
+  dynamic: true,
+  contexts: ["settings", "finance"],
+  contextGate: { anyOf: ["settings", "finance"] },
+  cacheStable: false,
+  cacheScope: "turn",
+  position: 92,
+  async get(runtime: IAgentRuntime, _message: Memory, _state: State): Promise<ProviderResult> {
+    try {
+      const registry = runtime.getService("CLOUD_MODEL_REGISTRY") as
+        | CloudModelRegistryService
+        | undefined;
+
+      if (!registry) return { text: "" };
+
+      const cached = runtimeCaches.get(runtime);
+      if (cached && Date.now() - cached.at < TTL) {
+        const cachedValue = Object.fromEntries(
+          Object.entries(cached.value).slice(0, MAX_MODEL_PROVIDERS)
+        ) as ModelsByProvider;
+        return formatModels(cachedValue);
+      }
+
+      const byProvider = await registry.getModelsByProvider();
+
+      if (Object.keys(byProvider).length === 0) {
+        return { text: "" };
+      }
+
+      runtimeCaches.set(runtime, { value: byProvider, at: Date.now() });
+      const capped = Object.fromEntries(
+        Object.entries(byProvider).slice(0, MAX_MODEL_PROVIDERS)
+      ) as ModelsByProvider;
+      return formatModels(capped);
+    } catch {
+      return { text: "", values: {}, data: {} };
+    }
+  },
+};
+
+function formatModels(byProvider: ModelsByProvider): ProviderResult {
+  const providers = Object.keys(byProvider).sort().slice(0, MAX_MODEL_PROVIDERS);
+  const total = providers.reduce(
+    (n, provider) => n + byProvider[provider].slice(0, MAX_MODELS_PER_PROVIDER).length,
+    0
+  );
+
+  return {
+    text: `ElizaCloud: ${total} models (${providers.join(", ")})`,
+    values: {
+      cloudModelProviders: providers.join(","),
+      cloudModelCount: total,
+    },
+  };
+}

package/src/index.browser.ts

@@ -0,0 +1,10 @@
+import type { Plugin } from "@elizaos/core";
+
+export const elizaOSCloudPlugin: Plugin = {
+  name: "elizaOSCloud",
+  description:
+    "ElizaOS Cloud browser facade. Node-only routes and services are exported from the node entry.",
+};
+
+export * from "./types";
+export default elizaOSCloudPlugin;

package/src/index.node.ts

@@ -0,0 +1,39 @@
+import pluginDefault from "./index.js";
+
+export * from "./index.js";
+export default pluginDefault;
+
+// Node-only route handlers (depend on node:os and other node built-ins).
+export { handleCloudBillingRoute } from "./routes/cloud-billing-routes";
+export { handleCloudCompatRoute } from "./routes/cloud-compat-routes";
+export { handleCloudRelayRoute } from "./routes/cloud-relay-routes";
+export {
+  type CloudRouteState,
+  handleCloudRoute,
+} from "./routes/cloud-routes-autonomous";
+export type { CloudConfigLike } from "./routes/cloud-routes-autonomous";
+export { handleCloudStatusRoutes } from "./routes/cloud-status-routes";
+export { runCloudOnboarding, type CloudOnboardingResult } from "./onboarding";
+export { CloudManager, type CloudManagerCallbacks } from "./cloud/cloud-manager";
+export {
+  getOrCreateClientAddressKey,
+  persistCloudWalletCache,
+  provisionCloudWalletsBestEffort,
+} from "./cloud/cloud-wallet";
+export {
+  normalizeCloudSecret,
+  resolveCloudApiKey,
+} from "./cloud/cloud-api-key";
+export {
+  clearCloudSecrets,
+  getCloudSecret,
+  scrubCloudSecretsFromEnv,
+} from "./lib/cloud-secrets";
+export {
+  __resetCloudBaseUrlCache,
+  ensureCloudTtsApiKeyAlias,
+  handleCloudTtsPreviewRoute,
+  mirrorCompatHeaders,
+  resolveCloudTtsBaseUrl,
+  resolveElevenLabsApiKeyForCloudMode,
+} from "./lib/server-cloud-tts";