@hubfluencer/mcp 0.1.0

package/src/core.ts

@@ -0,0 +1,244 @@
+/**
+ * Pure, side-effect-free helpers shared by the server (index.ts) and its tests.
+ *
+ * These live outside index.ts on purpose: index.ts registers 23+ tools and
+ * connects an stdio transport at module load, so importing it from a unit test
+ * would boot a live MCP server. Everything here is dependency-light (crypto +
+ * path only) and safe to import in isolation.
+ */
+
+import { createHash } from "node:crypto";
+import { isAbsolute, resolve, sep } from "node:path";
+
+export type Kind = "short" | "editor";
+
+/**
+ * True if `hostname` is an IP literal in a private, loopback, link-local, or
+ * cloud-metadata range — i.e. somewhere we must never send a credential or
+ * exfiltrate bytes to, even over https. A non-IP hostname (a real DNS name) is
+ * treated as public/allowed: we can't resolve it here without a DNS lookup, and
+ * the threat model is a tampered base_url / API response pointing at an internal
+ * *literal* (e.g. 169.254.169.254, 10.x, ::1). Handles IPv4 dotted-quad, IPv6
+ * (incl. bracketed and zone-id forms), and IPv4-mapped IPv6.
+ */
+export function isPrivateOrMetadataHost(hostname: string): boolean {
+	// Strip IPv6 brackets and any zone id (e.g. "[fe80::1%eth0]" → "fe80::1").
+	let host = hostname.trim().toLowerCase();
+	if (host.startsWith("[") && host.endsWith("]")) host = host.slice(1, -1);
+	const zone = host.indexOf("%");
+	if (zone !== -1) host = host.slice(0, zone);
+
+	// IPv4 dotted-quad.
+	const v4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);
+	if (v4) {
+		const o = v4.slice(1).map(Number);
+		if (o.some((n) => n > 255)) return false; // not a valid IPv4 literal
+		return isPrivateV4(o[0], o[1]);
+	}
+
+	// IPv6 (anything with a colon). Normalize away an IPv4-mapped suffix first.
+	if (host.includes(":")) {
+		// ::ffff:a.b.c.d / ::a.b.c.d — judge by the embedded IPv4.
+		const mapped = /(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/.exec(host);
+		if (mapped) {
+			const o = mapped[1].split(".").map(Number);
+			if (!o.some((n) => n > 255) && isPrivateV4(o[0], o[1])) {
+				return true;
+			}
+		}
+		if (host === "::1" || host === "::") return true; // loopback / unspecified
+		if (host === "::ffff:0:0") return true;
+		// fc00::/7 (unique-local) and fe80::/10 (link-local).
+		if (/^f[cd]/.test(host)) return true;
+		if (/^fe[89ab]/.test(host)) return true;
+		return false;
+	}
+
+	return false;
+}
+
+// Classifies an IPv4 address by its first two octets — all the blocked ranges
+// (loopback, RFC-1918 private, link-local/metadata, unspecified) are determined
+// by a/b alone, so c/d aren't needed.
+function isPrivateV4(a: number, b: number): boolean {
+	if (a === 127) return true; // 127.0.0.0/8 loopback
+	if (a === 10) return true; // 10.0.0.0/8
+	if (a === 172 && b >= 16 && b <= 31) return true; // 172.16.0.0/12
+	if (a === 192 && b === 168) return true; // 192.168.0.0/16
+	if (a === 169 && b === 254) return true; // 169.254.0.0/16 link-local + metadata
+	if (a === 0) return true; // 0.0.0.0/8 (incl. 0.0.0.0)
+	return false;
+}
+
+/**
+ * Guards a URL we're about to send a credential to, or fetch/PUT bytes against:
+ * the base API URL (assertSafeBaseUrl) AND every server-returned presigned /
+ * download URL (uploads.ts / index.ts). Requires https — refusing an http
+ * downgrade that would leak the token in cleartext or move file bytes in the
+ * clear — and refuses any private/link-local/metadata IP literal so a tampered
+ * base_url or a compromised/MITM'd API response can't redirect the credential
+ * or the bytes to an internal host (SSRF). Loopback http is allowed ONLY when
+ * `allowLoopback` is set (local development). NEVER include a token in the
+ * thrown message.
+ */
+export function assertSafeFetchUrl(
+	url: string,
+	opts: { allowLoopback?: boolean } = {},
+): URL {
+	let u: URL;
+	try {
+		u = new URL(url);
+	} catch {
+		throw new Error(`Invalid Hubfluencer URL: ${url}`);
+	}
+	const host = u.hostname;
+	const isLoopback =
+		host === "localhost" ||
+		host === "127.0.0.1" ||
+		host === "::1" ||
+		host === "[::1]";
+
+	if (u.protocol === "https:") {
+		// https is necessary but not sufficient — a private/metadata IP literal
+		// over https is still an internal-redirect we refuse.
+		if (isPrivateOrMetadataHost(host)) {
+			throw new Error(
+				`Refusing to use a Hubfluencer URL pointing at a private/internal host (${host}). ` +
+					"Use the public https endpoint.",
+			);
+		}
+		return u;
+	}
+
+	// Non-https: only loopback, only when explicitly allowed (local dev).
+	if (opts.allowLoopback && isLoopback) return u;
+
+	throw new Error(
+		`Refusing to use an insecure Hubfluencer URL (${u.protocol}//${host}). ` +
+			"Use an https URL (or localhost for local development).",
+	);
+}
+
+export interface NormalizedStatus {
+	kind: Kind;
+	slug: string;
+	stage: string;
+	terminal: boolean;
+	ready: boolean;
+	video_url: string | null;
+	error: string | null;
+}
+
+export function asRecord(v: unknown): Record<string, unknown> {
+	return v && typeof v === "object" ? (v as Record<string, unknown>) : {};
+}
+
+/** Collapses the short/editor state payloads into one shape the agent can poll. */
+export function normalizeStatus(
+	kind: Kind,
+	slug: string,
+	data: unknown,
+): NormalizedStatus {
+	const d = asRecord(data);
+	const latest = asRecord(d.latest_render);
+	const videoUrl = (latest.video_url as string) ?? null;
+
+	if (kind === "short") {
+		const stage = (d.stage as string) ?? "unknown";
+		return {
+			kind,
+			slug,
+			stage,
+			terminal: stage === "video_ready" || stage === "failed",
+			ready: stage === "video_ready",
+			video_url: videoUrl,
+			error: (d.error_message as string) ?? null,
+		};
+	}
+
+	// editor
+	const autopilot = (d.autopilot_status as string) ?? "unknown";
+	const renderStatus = (latest.status as string) ?? null;
+	const ready = renderStatus === "completed" && Boolean(videoUrl);
+	const terminal =
+		ready ||
+		autopilot === "failed" ||
+		autopilot === "cancelled" ||
+		renderStatus === "failed";
+	return {
+		kind,
+		slug,
+		stage: autopilot,
+		terminal,
+		ready,
+		video_url: videoUrl,
+		error: (d.autopilot_error_message as string) ?? null,
+	};
+}
+
+/** Stable idempotency key for a logical operation, so a retried call is safe. */
+export function idemKey(...parts: string[]): string {
+	return createHash("sha256")
+		.update(parts.join("|"))
+		.digest("hex")
+		.slice(0, 32);
+}
+
+/**
+ * Confines a model-supplied save_path to an allowlisted output base so a
+ * prompt-injected path can't write outside it (e.g. ~/.ssh/authorized_keys).
+ * Base = HUBFLUENCER_OUTPUT_DIR if set, else the current working directory.
+ * Rejects traversal and any non-.mp4 target.
+ */
+export function resolveSavePath(savePath: string): string {
+	const base = resolve(process.env.HUBFLUENCER_OUTPUT_DIR || process.cwd());
+	const target = isAbsolute(savePath)
+		? resolve(savePath)
+		: resolve(base, savePath);
+	if (!target.toLowerCase().endsWith(".mp4")) {
+		throw new Error("save_path must end in .mp4");
+	}
+	if (target !== base && !target.startsWith(base + sep)) {
+		throw new Error(
+			`save_path must be inside ${base} (set HUBFLUENCER_OUTPUT_DIR to change). Refusing to write to ${target}.`,
+		);
+	}
+	return target;
+}
+
+/**
+ * Picks short vs editor for make_video's kind:"auto".
+ *
+ * Bias: an ad/commercial/promo/story brief → the multi-scene EDITOR ad (what
+ * someone asking for "a full ad" pictures), UNLESS the prompt explicitly asks
+ * for something brief/simple → the cheaper single-clip SHORT. A prompt with no
+ * signal at all falls back to the cheaper short. The product is bilingual
+ * (EN/FR); accented chars don't sit on \b cleanly, so the FR patterns avoid
+ * word boundaries.
+ *
+ * Whatever this returns, make_video surfaces it (kind_inferred) plus the priced
+ * cost before charging, so a wrong guess is visible and overridable — never a
+ * silent expensive surprise.
+ */
+export function inferKind(prompt: string): Kind {
+	const p = prompt.toLowerCase();
+
+	// Explicit "keep it short/simple" intent wins — route to the cheap short. A
+	// bare duration ("a 30 second ad") is deliberately NOT a brevity signal: many
+	// ad briefs name a length, and it shouldn't override clear ad/story intent.
+	const wantsShort =
+		/\b(short|quick|simple|snappy|single[- ]?clip|one[- ]?clip|teaser)\b/.test(
+			p,
+		) || /(rapide|simple|court|clip unique|tease?r)/.test(p);
+	if (wantsShort) return "short";
+
+	// Ad / marketing / multi-scene / story intent → the full multi-scene editor.
+	const wantsEditor =
+		/\b(ads?|advert|advertisement|commercial|promo|campaign|launch|brand|story|stories|multi[- ]?scene|scenes?|narrat|explainer|chapters?|episodes?|testimonial|showcase|walkthrough|demo|spot)\b/.test(
+			p,
+		) ||
+		/(pub(licit[ée])?|annonce|campagne|histoire|multi[- ]?sc[eè]ne|sc[eè]nes?|raconte|chapitres?|[eé]pisodes?|explicat|lancement|t[eé]moignage|d[eé]mo|vitrine)/.test(
+			p,
+		);
+	return wantsEditor ? "editor" : "short";
+}

package/src/credentials.ts

@@ -0,0 +1,48 @@
+/**
+ * Local credential store for the device-link flow. The CLI writes the scoped
+ * access token here (mode 0600); the MCP server reads it as a fallback when
+ * HUBFLUENCER_API_TOKEN isn't set in the environment.
+ */
+
+import { readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export const CREDENTIALS_PATH =
+	process.env.HUBFLUENCER_CREDENTIALS ||
+	join(homedir(), ".hubfluencer", "credentials.json");
+
+export interface StoredCredentials {
+	token?: string;
+	base_url?: string;
+}
+
+export function readStoredCredentials(): StoredCredentials {
+	let raw: string;
+	try {
+		raw = readFileSync(CREDENTIALS_PATH, "utf8");
+	} catch {
+		return {};
+	}
+	// Best-effort warning if the token file is group/world-accessible — it holds a
+	// long-lived account credential. POSIX only; Windows reports mode oddly so we
+	// skip the check there. Never blocks the read.
+	if (process.platform !== "win32") {
+		try {
+			const mode = statSync(CREDENTIALS_PATH).mode;
+			if (mode & 0o077) {
+				console.error(
+					`Warning: ${CREDENTIALS_PATH} is accessible to other users ` +
+						`(mode ${(mode & 0o777).toString(8)}). Run: chmod 600 ${CREDENTIALS_PATH}`,
+				);
+			}
+		} catch {
+			// stat is advisory — never fail the read over it
+		}
+	}
+	try {
+		return JSON.parse(raw) as StoredCredentials;
+	} catch {
+		return {};
+	}
+}