@syengup/friday-channel-next 0.1.26 → 0.1.28

package/src/link-preview/ssrf-guard.ts

@@ -0,0 +1,229 @@
+/**
+ * SSRF guard + restricted fetch for the link-preview endpoint.
+ *
+ * Unlike `downloadRemoteMedia` (agent-supplied URLs for outbound media), link-preview fetches
+ * URLs that originate from arbitrary message text, so every hop must be validated: protocol,
+ * port, hostname literals, and the full set of DNS-resolved addresses. Redirects are followed
+ * manually so each target is re-checked before the next request.
+ *
+ * Known residual risk: DNS rebinding TOCTOU — we validate resolved addresses, then `fetch`
+ * resolves again. Closing that gap requires dialing by IP with SNI/Host rewriting, which is
+ * disproportionate for preview metadata; accepted at this threat level.
+ */
+
+import dns from "node:dns/promises";
+import net from "node:net";
+
+const MAX_REDIRECTS = 5;
+
+export class BlockedUrlError extends Error {
+  readonly reason: string;
+  constructor(reason: string) {
+    super(`Blocked URL: ${reason}`);
+    this.name = "BlockedUrlError";
+    this.reason = reason;
+  }
+}
+
+/** Parse an absolute http/https URL. Returns null for anything else (caller maps to invalid_url). */
+export function parseHttpUrl(raw: string): URL | null {
+  let url: URL;
+  try {
+    url = new URL(raw.trim());
+  } catch {
+    return null;
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") return null;
+  return url;
+}
+
+const BLOCKED_HOST_SUFFIXES = [".local", ".internal", ".home.arpa", ".localhost"];
+
+/** Synchronous literal checks: port, hostname blocklist, IP-literal hosts. Throws BlockedUrlError. */
+export function assertPublicHttpUrl(url: URL): void {
+  if (url.port && url.port !== "80" && url.port !== "443") {
+    throw new BlockedUrlError(`port ${url.port} not allowed`);
+  }
+  const host = url.hostname.toLowerCase().replace(/\.$/, "");
+  if (!host) throw new BlockedUrlError("empty host");
+  if (host === "localhost" || BLOCKED_HOST_SUFFIXES.some((s) => host.endsWith(s))) {
+    throw new BlockedUrlError(`host "${host}" is not public`);
+  }
+  // IPv6 literal in a URL comes bracketed: strip for net.isIP.
+  const bareHost = host.startsWith("[") && host.endsWith("]") ? host.slice(1, -1) : host;
+  if (net.isIP(bareHost) && isPrivateAddress(bareHost)) {
+    throw new BlockedUrlError(`address ${bareHost} is private/reserved`);
+  }
+}
+
+/** True when the IP (v4 or v6, including ::ffff: mapped v4) is private, loopback, or reserved. */
+export function isPrivateAddress(ip: string): boolean {
+  const version = net.isIP(ip);
+  if (version === 4) return isPrivateIPv4(ip);
+  if (version === 6) return isPrivateIPv6(ip);
+  return true; // not an IP at all — treat as unsafe
+}
+
+function isPrivateIPv4(ip: string): boolean {
+  const parts = ip.split(".").map(Number);
+  if (parts.length !== 4 || parts.some((n) => !Number.isInteger(n) || n < 0 || n > 255)) return true;
+  const [a, b] = parts;
+  if (a === 0) return true; // 0.0.0.0/8
+  if (a === 10) return true; // 10/8
+  if (a === 100 && b >= 64 && b <= 127) return true; // 100.64/10 CGNAT
+  if (a === 127) return true; // loopback
+  if (a === 169 && b === 254) return true; // link-local
+  if (a === 172 && b >= 16 && b <= 31) return true; // 172.16/12
+  if (a === 192 && b === 0 && parts[2] === 0) return true; // 192.0.0/24
+  if (a === 192 && b === 168) return true; // 192.168/16
+  // 198.18/15 (benchmarking) intentionally NOT blocked: fake-IP DNS setups (clash/surge tun
+  // mode, common on gateway hosts) resolve EVERY domain into this range, so blocking it kills
+  // all lookups. The range is not used for real LAN services, so the SSRF exposure is nil.
+  if (a >= 224) return true; // multicast 224/4 + reserved 240/4 + broadcast
+  return false;
+}
+
+function isPrivateIPv6(ip: string): boolean {
+  const lower = ip.toLowerCase();
+  // ::ffff:a.b.c.d mapped IPv4 → validate the embedded v4.
+  const mapped = lower.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/);
+  if (mapped) return isPrivateIPv4(mapped[1]);
+  if (lower === "::" || lower === "::1") return true; // unspecified / loopback
+  const head = lower.split(":")[0];
+  if (head.startsWith("fc") || head.startsWith("fd")) return true; // fc00::/7 ULA
+  if (/^fe[89ab]/.test(head)) return true; // fe80::/10 link-local
+  return false;
+}
+
+/** Resolve the hostname and require every returned address to be public. Throws BlockedUrlError. */
+export async function assertResolvesPublic(url: URL): Promise<void> {
+  const host = url.hostname.replace(/^\[|\]$/g, "");
+  if (net.isIP(host)) {
+    if (isPrivateAddress(host)) throw new BlockedUrlError(`address ${host} is private/reserved`);
+    return;
+  }
+  let addresses: { address: string }[];
+  try {
+    addresses = await dns.lookup(host, { all: true, verbatim: true });
+  } catch {
+    throw new Error(`DNS lookup failed for ${host}`);
+  }
+  if (!addresses.length) throw new Error(`DNS lookup returned no addresses for ${host}`);
+  for (const { address } of addresses) {
+    if (isPrivateAddress(address)) {
+      throw new BlockedUrlError(`${host} resolves to private/reserved address ${address}`);
+    }
+  }
+}
+
+export interface FetchPublicUrlOptions {
+  maxBytes: number;
+  timeoutMs: number;
+  /** Sent as the Accept header. */
+  accept?: string;
+  /** When set, the response Content-Type must start with one of these prefixes. */
+  requireContentTypePrefixes?: string[];
+}
+
+export interface FetchPublicUrlResult {
+  finalUrl: string;
+  contentType: string;
+  body: Buffer;
+}
+
+const PREVIEW_USER_AGENT = "Mozilla/5.0 (compatible; OpenClawLinkPreview/1.0)";
+
+/**
+ * Fetch a public http/https URL with manual redirects (≤5 hops, each hop re-validated) and a
+ * streamed size cap (Content-Length is not trusted). Returns null on ordinary failures (non-2xx,
+ * oversize, timeout, bad content type, DNS error); throws BlockedUrlError on SSRF rejection.
+ */
+export async function fetchPublicUrl(
+  rawUrl: string,
+  opts: FetchPublicUrlOptions,
+): Promise<FetchPublicUrlResult | null> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), opts.timeoutMs);
+  try {
+    let current = rawUrl;
+    for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
+      const url = parseHttpUrl(current);
+      if (!url) return null;
+      assertPublicHttpUrl(url);
+      await assertResolvesPublic(url);
+
+      const res = await fetch(url, {
+        redirect: "manual",
+        signal: controller.signal,
+        headers: {
+          "User-Agent": PREVIEW_USER_AGENT,
+          ...(opts.accept ? { Accept: opts.accept } : {}),
+        },
+      });
+
+      if (res.status >= 300 && res.status < 400) {
+        const location = res.headers.get("location");
+        await res.body?.cancel().catch(() => {});
+        if (!location) return null;
+        try {
+          current = new URL(location, url).toString();
+        } catch {
+          return null;
+        }
+        continue;
+      }
+      if (!res.ok) {
+        await res.body?.cancel().catch(() => {});
+        return null;
+      }
+
+      const contentType = res.headers.get("content-type")?.trim().toLowerCase() ?? "";
+      if (
+        opts.requireContentTypePrefixes &&
+        !opts.requireContentTypePrefixes.some((p) => contentType.startsWith(p))
+      ) {
+        await res.body?.cancel().catch(() => {});
+        return null;
+      }
+
+      const body = await readBodyCapped(res, opts.maxBytes);
+      if (body === null) return null;
+      return { finalUrl: url.toString(), contentType, body };
+    }
+    return null; // too many redirects
+  } catch (err) {
+    if (err instanceof BlockedUrlError) throw err;
+    return null; // timeout / network / DNS failure
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** Stream the response body, aborting once it exceeds maxBytes. */
+async function readBodyCapped(res: Response, maxBytes: number): Promise<Buffer | null> {
+  if (!res.body) {
+    const buffer = Buffer.from(await res.arrayBuffer());
+    return buffer.length <= maxBytes ? buffer : null;
+  }
+  const reader = res.body.getReader();
+  const chunks: Buffer[] = [];
+  let total = 0;
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      if (value) {
+        total += value.byteLength;
+        if (total > maxBytes) {
+          await reader.cancel().catch(() => {});
+          return null;
+        }
+        chunks.push(Buffer.from(value));
+      }
+    }
+  } catch {
+    return null;
+  }
+  const buffer = Buffer.concat(chunks);
+  return buffer.length ? buffer : null;
+}

package/src/plugin-install-info.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vitest";
+import { semverGreater } from "./plugin-install-info.js";
+
+describe("semverGreater", () => {
+  it("returns true when a is a higher patch/minor/major", () => {
+    expect(semverGreater("0.1.27", "0.1.26")).toBe(true);
+    expect(semverGreater("0.2.0", "0.1.99")).toBe(true);
+    expect(semverGreater("1.0.0", "0.9.9")).toBe(true);
+  });
+
+  it("returns false when equal or lower", () => {
+    expect(semverGreater("0.1.27", "0.1.27")).toBe(false);
+    expect(semverGreater("0.1.26", "0.1.27")).toBe(false);
+    expect(semverGreater("0.1.0", "0.1.0")).toBe(false);
+  });
+
+  it("tolerates a leading v and pre-release/build suffixes", () => {
+    expect(semverGreater("v0.1.27", "0.1.26")).toBe(true);
+    expect(semverGreater("0.1.27-beta.1", "0.1.26")).toBe(true);
+    expect(semverGreater("0.1.27", "0.1.27-rc.1")).toBe(false);
+  });
+
+  it("returns false for null/undefined inputs", () => {
+    expect(semverGreater(null, "0.1.0")).toBe(false);
+    expect(semverGreater("0.1.0", null)).toBe(false);
+    expect(semverGreater(undefined, undefined)).toBe(false);
+  });
+});

package/src/plugin-install-info.ts

@@ -0,0 +1,95 @@
+/**
+ * Helpers for the plugin upgrade feature: read this plugin's install record
+ * (source: "npm" vs "path"/dev), compare semver, and look up the latest version
+ * published to the npm registry (cached).
+ */
+import { getUpgradeRuntime } from "./upgrade-runtime.js";
+import { PLUGIN_ID, PLUGIN_PACKAGE_NAME } from "./version.js";
+
+/** Install source from the OpenClaw config `plugins.installs[<id>].source`. */
+export type InstallSource = "npm" | "path" | "archive" | "clawhub" | "git" | "marketplace" | "unknown";
+
+/**
+ * Read the install source for this plugin from the live config snapshot.
+ * Returns "unknown" when the record can't be resolved (e.g. runtime not captured).
+ * Only "npm" is auto-upgradable; "path" means a dev (load.paths) install which must
+ * never be npm-upgraded (would duplicate-install and break agent media sends).
+ */
+export function getInstallSource(): InstallSource {
+  const rt = getUpgradeRuntime();
+  if (!rt) return "unknown";
+  try {
+    const cfg = rt.currentConfig() as {
+      plugins?: { installs?: Record<string, { source?: string } | undefined> };
+    } | undefined;
+    const source = cfg?.plugins?.installs?.[PLUGIN_ID]?.source;
+    if (
+      source === "npm" ||
+      source === "path" ||
+      source === "archive" ||
+      source === "clawhub" ||
+      source === "git" ||
+      source === "marketplace"
+    ) {
+      return source;
+    }
+    return "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
+/** Compare dotted numeric versions. Returns true if `a` is strictly greater than `b`. */
+export function semverGreater(a: string | null | undefined, b: string | null | undefined): boolean {
+  if (!a || !b) return false;
+  const pa = parseSemver(a);
+  const pb = parseSemver(b);
+  for (let i = 0; i < 3; i++) {
+    if (pa[i] > pb[i]) return true;
+    if (pa[i] < pb[i]) return false;
+  }
+  return false;
+}
+
+function parseSemver(v: string): [number, number, number] {
+  // Strip a leading "v" and any pre-release/build suffix, keep major.minor.patch.
+  const core = v.trim().replace(/^v/i, "").split(/[-+]/)[0];
+  const parts = core.split(".").map((p) => Number.parseInt(p, 10));
+  return [parts[0] || 0, parts[1] || 0, parts[2] || 0];
+}
+
+let cachedLatest: { version: string | null; fetchedAt: number } | null = null;
+const LATEST_TTL_MS = 10 * 60 * 1000;
+
+/** Fetch the latest published version from the npm registry (cached ~10min). Null on failure. */
+export async function fetchLatestVersion(nowMs: number): Promise<string | null> {
+  if (cachedLatest && nowMs - cachedLatest.fetchedAt < LATEST_TTL_MS) {
+    return cachedLatest.version;
+  }
+  let version: string | null = null;
+  try {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 5000);
+    try {
+      const res = await fetch(
+        `https://registry.npmjs.org/${PLUGIN_PACKAGE_NAME}/latest`,
+        { signal: controller.signal, headers: { Accept: "application/json" } },
+      );
+      if (res.ok) {
+        const body = (await res.json()) as { version?: string };
+        if (typeof body.version === "string" && body.version) version = body.version;
+      }
+    } finally {
+      clearTimeout(timer);
+    }
+  } catch {
+    version = null;
+  }
+  cachedLatest = { version, fetchedAt: nowMs };
+  return version;
+}
+
+/** Vitest-only */
+export function resetLatestVersionCacheForTest(): void {
+  cachedLatest = null;
+}

package/src/upgrade-runtime.ts

@@ -0,0 +1,69 @@
+/**
+ * Captures the full plugin runtime (`api.runtime`) at `registerFull` time so the
+ * plugin-info / plugin-upgrade HTTP handlers can reach `system.runCommandWithTimeout`
+ * and `config.mutateConfigFile` — capabilities the narrow `getFridayNextRuntime()`
+ * store does NOT expose (it only carries `config`/`logger`).
+ *
+ * Mirrors the `setFridayAgentForwardRuntime` capture pattern in agent-forward-runtime.ts.
+ */
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";
+
+export type SpawnResultLike = {
+  code: number | null;
+  stdout: string;
+  stderr: string;
+  [key: string]: unknown;
+};
+
+export type ConfigAfterWrite =
+  | { mode: "auto" }
+  | { mode: "restart"; reason: string }
+  | { mode: "none"; reason: string };
+
+export type UpgradeRuntime = {
+  /** Run a command (argv) with a timeout in ms; resolves with stdout/stderr/code. */
+  runCommandWithTimeout: (argv: string[], timeoutMs: number) => Promise<SpawnResultLike>;
+  /** Read the current (deep-readonly) OpenClaw config snapshot. */
+  currentConfig: () => unknown;
+  /** Mutate the config file; `afterWrite: { mode: "restart" }` triggers a safe gateway restart. */
+  mutateConfigFile: (params: {
+    afterWrite: ConfigAfterWrite;
+    mutate: (draft: unknown) => unknown | void;
+  }) => Promise<unknown>;
+};
+
+let upgradeRuntime: UpgradeRuntime | null = null;
+
+export function setUpgradeRuntime(api: OpenClawPluginApi): void {
+  const runtime = api.runtime as unknown as {
+    system?: { runCommandWithTimeout?: (argv: string[], opts: unknown) => Promise<SpawnResultLike> };
+    config: {
+      current: () => unknown;
+      mutateConfigFile?: (params: unknown) => Promise<unknown>;
+    };
+  };
+
+  upgradeRuntime = {
+    runCommandWithTimeout: async (argv, timeoutMs) => {
+      const run = runtime.system?.runCommandWithTimeout;
+      if (!run) throw new Error("runtime.system.runCommandWithTimeout unavailable");
+      // `runCommandWithTimeout(argv, number | CommandOptions)` — pass the bare ms.
+      return run(argv, timeoutMs);
+    },
+    currentConfig: () => runtime.config.current(),
+    mutateConfigFile: async (params) => {
+      const mutate = runtime.config.mutateConfigFile;
+      if (!mutate) throw new Error("runtime.config.mutateConfigFile unavailable");
+      return mutate(params);
+    },
+  };
+}
+
+export function getUpgradeRuntime(): UpgradeRuntime | null {
+  return upgradeRuntime;
+}
+
+/** Vitest-only */
+export function resetUpgradeRuntimeForTest(): void {
+  upgradeRuntime = null;
+}

package/src/version.ts

@@ -0,0 +1,41 @@
+/**
+ * Plugin self-version.
+ *
+ * Resolved at module load by reading this package's own package.json relative to
+ * the compiled module URL. `tsc` does NOT copy package.json into `dist/`, and a
+ * JSON `import` would rewrite to a non-existent `dist/package.json`, so we read
+ * the real file from disk and walk a couple of candidate paths. Falls back to a
+ * hardcoded constant if the file can't be located (keep in sync with package.json).
+ */
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+/** Keep in sync with package.json "version" as a last-resort fallback. */
+const FALLBACK_VERSION = "0.1.28";
+
+function resolvePluginVersion(): string {
+  // dist layout: <root>/dist/src/version.js → ../../package.json = <root>/package.json
+  // source layout (vitest/jiti): <root>/src/version.ts → ../package.json = <root>/package.json
+  const candidates = ["../../package.json", "../package.json"];
+  for (const rel of candidates) {
+    try {
+      const path = fileURLToPath(new URL(rel, import.meta.url));
+      const raw = readFileSync(path, "utf8");
+      const pkg = JSON.parse(raw) as { name?: string; version?: string };
+      if (pkg.name === "@syengup/friday-channel-next" && typeof pkg.version === "string" && pkg.version) {
+        return pkg.version;
+      }
+    } catch {
+      // try next candidate
+    }
+  }
+  return FALLBACK_VERSION;
+}
+
+export const PLUGIN_VERSION: string = resolvePluginVersion();
+
+/** npm package name, used for the upgrade spec and registry lookup. */
+export const PLUGIN_PACKAGE_NAME = "@syengup/friday-channel-next";
+
+/** Plugin id as registered with OpenClaw (used to read the install record). */
+export const PLUGIN_ID = "friday-next";