emdash 0.0.0-a → 0.0.1

package/src/plugins/manifest-schema.ts

@@ -0,0 +1,230 @@
+/**
+ * Zod schema for PluginManifest validation
+ *
+ * Used to validate manifest.json from plugin bundles at every parse site:
+ * - Client-side download (marketplace.ts extractBundle)
+ * - R2 load (api/handlers/marketplace.ts loadBundleFromR2)
+ * - CLI publish preview (cli/commands/publish.ts readManifestFromTarball)
+ * - Marketplace ingest extends this with publishing-specific fields
+ */
+
+import { z } from "zod";
+
+// ── Enum values (must stay in sync with types.ts) ───────────────
+
+export const PLUGIN_CAPABILITIES = [
+	"network:fetch",
+	"network:fetch:any",
+	"read:content",
+	"write:content",
+	"read:media",
+	"write:media",
+	"read:users",
+	"email:send",
+	"email:provide",
+	"email:intercept",
+	"page:inject",
+] as const;
+
+/** Must stay in sync with FieldType in schema/types.ts */
+const FIELD_TYPES = [
+	"string",
+	"text",
+	"number",
+	"integer",
+	"boolean",
+	"datetime",
+	"select",
+	"multiSelect",
+	"portableText",
+	"image",
+	"file",
+	"reference",
+	"json",
+	"slug",
+] as const;
+
+export const HOOK_NAMES = [
+	"plugin:install",
+	"plugin:activate",
+	"plugin:deactivate",
+	"plugin:uninstall",
+	"content:beforeSave",
+	"content:afterSave",
+	"content:beforeDelete",
+	"content:afterDelete",
+	"media:beforeUpload",
+	"media:afterUpload",
+	"cron",
+	"email:beforeSend",
+	"email:deliver",
+	"email:afterSend",
+	"comment:beforeCreate",
+	"comment:moderate",
+	"comment:afterCreate",
+	"comment:afterModerate",
+	"page:metadata",
+	"page:fragments",
+] as const;
+
+/**
+ * Structured hook entry for manifest — name plus optional metadata.
+ * During a transition period, both plain strings and objects are accepted.
+ */
+const manifestHookEntrySchema = z.object({
+	name: z.enum(HOOK_NAMES),
+	exclusive: z.boolean().optional(),
+	priority: z.number().int().optional(),
+	timeout: z.number().int().positive().optional(),
+});
+
+/**
+ * Structured route entry for manifest — name plus optional metadata.
+ * Both plain strings and objects are accepted; strings are normalized
+ * to `{ name }` objects via `normalizeManifestRoute()`.
+ */
+/** Route names must be safe path segments — alphanumeric, hyphens, underscores, forward slashes */
+const routeNamePattern = /^[a-zA-Z0-9][a-zA-Z0-9_\-/]*$/;
+
+const manifestRouteEntrySchema = z.object({
+	name: z.string().min(1).regex(routeNamePattern, "Route name must be a safe path segment"),
+	public: z.boolean().optional(),
+});
+
+// ── Sub-schemas ─────────────────────────────────────────────────
+
+/** Index field names must be valid identifiers to prevent SQL injection via JSON path expressions */
+const indexFieldName = z.string().regex(/^[a-zA-Z][a-zA-Z0-9_]*$/);
+
+const storageCollectionSchema = z.object({
+	indexes: z.array(z.union([indexFieldName, z.array(indexFieldName)])),
+	uniqueIndexes: z.array(z.union([indexFieldName, z.array(indexFieldName)])).optional(),
+});
+
+const baseSettingFields = {
+	label: z.string(),
+	description: z.string().optional(),
+};
+
+const settingFieldSchema = z.discriminatedUnion("type", [
+	z.object({
+		...baseSettingFields,
+		type: z.literal("string"),
+		default: z.string().optional(),
+		multiline: z.boolean().optional(),
+	}),
+	z.object({
+		...baseSettingFields,
+		type: z.literal("number"),
+		default: z.number().optional(),
+		min: z.number().optional(),
+		max: z.number().optional(),
+	}),
+	z.object({ ...baseSettingFields, type: z.literal("boolean"), default: z.boolean().optional() }),
+	z.object({
+		...baseSettingFields,
+		type: z.literal("select"),
+		options: z.array(z.object({ value: z.string(), label: z.string() })),
+		default: z.string().optional(),
+	}),
+	z.object({ ...baseSettingFields, type: z.literal("secret") }),
+]);
+
+const adminPageSchema = z.object({
+	path: z.string(),
+	label: z.string(),
+	icon: z.string().optional(),
+});
+
+const dashboardWidgetSchema = z.object({
+	id: z.string(),
+	size: z.enum(["full", "half", "third"]).optional(),
+	title: z.string().optional(),
+});
+
+const pluginAdminConfigSchema = z.object({
+	entry: z.string().optional(),
+	settingsSchema: z.record(z.string(), settingFieldSchema).optional(),
+	pages: z.array(adminPageSchema).optional(),
+	widgets: z.array(dashboardWidgetSchema).optional(),
+	fieldWidgets: z
+		.array(
+			z.object({
+				name: z.string().min(1),
+				label: z.string().min(1),
+				fieldTypes: z.array(z.enum(FIELD_TYPES)),
+				elements: z
+					.array(
+						z
+							.object({
+								type: z.string(),
+								action_id: z.string(),
+								label: z.string().optional(),
+							})
+							.passthrough(),
+					)
+					.optional(),
+			}),
+		)
+		.optional(),
+});
+
+// ── Main schema ─────────────────────────────────────────────────
+
+/**
+ * Zod schema matching the PluginManifest interface from types.ts.
+ *
+ * Every JSON.parse of a manifest.json should validate through this.
+ */
+export const pluginManifestSchema = z.object({
+	id: z.string().min(1),
+	version: z.string().min(1),
+	capabilities: z.array(z.enum(PLUGIN_CAPABILITIES)),
+	allowedHosts: z.array(z.string()),
+	storage: z.record(z.string(), storageCollectionSchema),
+	/**
+	 * Hook declarations — accepts both plain name strings (legacy) and
+	 * structured objects with exclusive/priority/timeout metadata.
+	 * Plain strings are normalized to `{ name }` objects after parsing.
+	 */
+	hooks: z.array(z.union([z.enum(HOOK_NAMES), manifestHookEntrySchema])),
+	/**
+	 * Route declarations — accepts both plain name strings and
+	 * structured objects with public metadata.
+	 * Plain strings are normalized to `{ name }` objects after parsing.
+	 */
+	routes: z.array(
+		z.union([
+			z.string().min(1).regex(routeNamePattern, "Route name must be a safe path segment"),
+			manifestRouteEntrySchema,
+		]),
+	),
+	admin: pluginAdminConfigSchema,
+});
+
+export type ValidatedPluginManifest = z.infer<typeof pluginManifestSchema>;
+
+/**
+ * Normalize a manifest hook entry — plain strings become `{ name }` objects.
+ */
+export function normalizeManifestHook(
+	entry: string | { name: string; exclusive?: boolean; priority?: number; timeout?: number },
+): { name: string; exclusive?: boolean; priority?: number; timeout?: number } {
+	if (typeof entry === "string") {
+		return { name: entry };
+	}
+	return entry;
+}
+
+/**
+ * Normalize a manifest route entry — plain strings become `{ name }` objects.
+ */
+export function normalizeManifestRoute(entry: string | { name: string; public?: boolean }): {
+	name: string;
+	public?: boolean;
+} {
+	if (typeof entry === "string") {
+		return { name: entry };
+	}
+	return entry;
+}

package/src/plugins/marketplace.ts

@@ -0,0 +1,460 @@
+/**
+ * MarketplaceClient — HTTP client for the EmDash Plugin Marketplace
+ *
+ * Used by the install/update/proxy endpoints in EmDash core to communicate
+ * with the marketplace Worker. The marketplace is a distribution channel,
+ * not a runtime dependency — bundles are copied to site-local R2 at install time.
+ */
+
+import { createGzipDecoder, unpackTar } from "modern-tar";
+
+import { pluginManifestSchema } from "./manifest-schema.js";
+import type { PluginManifest } from "./types.js";
+
+// ── Module-level regex patterns ───────────────────────────────────
+
+const TRAILING_SLASHES = /\/+$/;
+const LEADING_DOT_SLASH = /^\.\//;
+
+// ── Types ──────────────────────────────────────────────────────────
+
+export interface MarketplacePluginSummary {
+	id: string;
+	name: string;
+	description: string | null;
+	author: {
+		name: string;
+		verified: boolean;
+		avatarUrl: string | null;
+	};
+	capabilities: string[];
+	keywords: string[];
+	installCount: number;
+	hasIcon: boolean;
+	iconUrl: string;
+	latestVersion?: {
+		version: string;
+		audit?: {
+			verdict: string;
+			riskScore: number;
+		};
+		imageAudit?: {
+			verdict: string;
+		};
+	};
+	createdAt: string;
+	updatedAt: string;
+}
+
+export interface MarketplaceVersionSummary {
+	version: string;
+	minEmDashVersion: string | null;
+	bundleSize: number;
+	checksum: string;
+	changelog: string | null;
+	capabilities: string[];
+	status: string;
+	auditVerdict: string | null;
+	imageAuditVerdict: string | null;
+	publishedAt: string;
+}
+
+export interface MarketplacePluginDetail extends MarketplacePluginSummary {
+	repositoryUrl: string | null;
+	homepageUrl: string | null;
+	license: string | null;
+	latestVersion?: {
+		version: string;
+		minEmDashVersion: string | null;
+		bundleSize: number;
+		checksum: string;
+		changelog: string | null;
+		readme: string | null;
+		hasIcon: boolean;
+		screenshotCount: number;
+		screenshotUrls: string[];
+		capabilities: string[];
+		status: string;
+		audit?: {
+			verdict: string;
+			riskScore: number;
+		};
+		imageAudit?: {
+			verdict: string;
+		};
+		publishedAt: string;
+	};
+}
+
+export interface MarketplaceSearchOpts {
+	category?: string;
+	capability?: string;
+	sort?: "installs" | "updated" | "created" | "name";
+	cursor?: string;
+	limit?: number;
+}
+
+export interface MarketplaceSearchResult {
+	items: MarketplacePluginSummary[];
+	nextCursor?: string;
+}
+
+// ── Theme types ───────────────────────────────────────────────────
+
+export interface MarketplaceThemeSummary {
+	id: string;
+	name: string;
+	description: string | null;
+	author: {
+		name: string;
+		verified: boolean;
+		avatarUrl: string | null;
+	};
+	keywords: string[];
+	previewUrl: string;
+	demoUrl: string | null;
+	hasThumbnail: boolean;
+	thumbnailUrl: string | null;
+	createdAt: string;
+	updatedAt: string;
+}
+
+export interface MarketplaceThemeDetail extends MarketplaceThemeSummary {
+	author: {
+		id: string;
+		name: string;
+		verified: boolean;
+		avatarUrl: string | null;
+	};
+	repositoryUrl: string | null;
+	homepageUrl: string | null;
+	license: string | null;
+	screenshotCount: number;
+	screenshotUrls: string[];
+}
+
+export interface MarketplaceThemeSearchOpts {
+	keyword?: string;
+	sort?: "name" | "created" | "updated";
+	cursor?: string;
+	limit?: number;
+}
+
+export interface MarketplaceThemeSearchResult {
+	items: MarketplaceThemeSummary[];
+	nextCursor?: string;
+}
+
+export interface PluginBundle {
+	manifest: PluginManifest;
+	backendCode: string;
+	adminCode?: string;
+	checksum: string;
+}
+
+// ── Interface ──────────────────────────────────────────────────────
+
+export interface MarketplaceClient {
+	/** Search the marketplace catalog */
+	search(query?: string, opts?: MarketplaceSearchOpts): Promise<MarketplaceSearchResult>;
+
+	/** Get full plugin detail */
+	getPlugin(id: string): Promise<MarketplacePluginDetail>;
+
+	/** Get version history for a plugin */
+	getVersions(id: string): Promise<MarketplaceVersionSummary[]>;
+
+	/** Download and extract a plugin bundle */
+	downloadBundle(id: string, version: string): Promise<PluginBundle>;
+
+	/** Fire-and-forget install stat (never throws) */
+	reportInstall(id: string, version: string): Promise<void>;
+
+	/** Search theme listings */
+	searchThemes(
+		query?: string,
+		opts?: MarketplaceThemeSearchOpts,
+	): Promise<MarketplaceThemeSearchResult>;
+
+	/** Get full theme detail */
+	getTheme(id: string): Promise<MarketplaceThemeDetail>;
+}
+
+// ── Errors ─────────────────────────────────────────────────────────
+
+export class MarketplaceError extends Error {
+	constructor(
+		message: string,
+		public readonly status?: number,
+		public readonly code?: string,
+	) {
+		super(message);
+		this.name = "MarketplaceError";
+	}
+}
+
+export class MarketplaceUnavailableError extends MarketplaceError {
+	constructor(cause?: unknown) {
+		super("Plugin marketplace is unavailable", undefined, "MARKETPLACE_UNAVAILABLE");
+		if (cause) this.cause = cause;
+	}
+}
+
+// ── Implementation ─────────────────────────────────────────────────
+
+class MarketplaceClientImpl implements MarketplaceClient {
+	private readonly baseUrl: string;
+
+	constructor(baseUrl: string) {
+		// Strip trailing slash
+		this.baseUrl = baseUrl.replace(TRAILING_SLASHES, "");
+	}
+
+	async search(query?: string, opts?: MarketplaceSearchOpts): Promise<MarketplaceSearchResult> {
+		const params = new URLSearchParams();
+		if (query) params.set("q", query);
+		if (opts?.category) params.set("category", opts.category);
+		if (opts?.capability) params.set("capability", opts.capability);
+		if (opts?.sort) params.set("sort", opts.sort);
+		if (opts?.cursor) params.set("cursor", opts.cursor);
+		if (opts?.limit) params.set("limit", String(opts.limit));
+
+		const qs = params.toString();
+		const url = `${this.baseUrl}/api/v1/plugins${qs ? `?${qs}` : ""}`;
+		const data = await this.fetchJson<MarketplaceSearchResult>(url);
+		return data;
+	}
+
+	async getPlugin(id: string): Promise<MarketplacePluginDetail> {
+		const url = `${this.baseUrl}/api/v1/plugins/${encodeURIComponent(id)}`;
+		return this.fetchJson<MarketplacePluginDetail>(url);
+	}
+
+	async getVersions(id: string): Promise<MarketplaceVersionSummary[]> {
+		const url = `${this.baseUrl}/api/v1/plugins/${encodeURIComponent(id)}/versions`;
+		const data = await this.fetchJson<{ items: MarketplaceVersionSummary[] }>(url);
+		return data.items;
+	}
+
+	async downloadBundle(id: string, version: string): Promise<PluginBundle> {
+		const bundleUrl = `${this.baseUrl}/api/v1/plugins/${encodeURIComponent(id)}/versions/${encodeURIComponent(version)}/bundle`;
+
+		let response: Response;
+		try {
+			response = await fetch(bundleUrl, {
+				redirect: "follow",
+			});
+		} catch (err) {
+			throw new MarketplaceUnavailableError(err);
+		}
+
+		if (!response.ok) {
+			throw new MarketplaceError(
+				`Failed to download bundle: ${response.status} ${response.statusText}`,
+				response.status,
+				"BUNDLE_DOWNLOAD_FAILED",
+			);
+		}
+
+		const tarballBytes = new Uint8Array(await response.arrayBuffer());
+		try {
+			return await extractBundle(tarballBytes);
+		} catch (err) {
+			if (err instanceof MarketplaceError) throw err;
+			throw new MarketplaceError(
+				"Failed to extract plugin bundle",
+				undefined,
+				"BUNDLE_EXTRACT_FAILED",
+			);
+		}
+	}
+
+	async reportInstall(id: string, version: string): Promise<void> {
+		// Generate a stable site hash (best-effort, non-identifying)
+		const siteHash = await generateSiteHash();
+		const url = `${this.baseUrl}/api/v1/plugins/${encodeURIComponent(id)}/installs`;
+
+		try {
+			await fetch(url, {
+				method: "POST",
+				headers: { "Content-Type": "application/json" },
+				body: JSON.stringify({ siteHash, version }),
+			});
+		} catch {
+			// Fire-and-forget — never throw
+		}
+	}
+
+	async searchThemes(
+		query?: string,
+		opts?: MarketplaceThemeSearchOpts,
+	): Promise<MarketplaceThemeSearchResult> {
+		const params = new URLSearchParams();
+		if (query) params.set("q", query);
+		if (opts?.keyword) params.set("keyword", opts.keyword);
+		if (opts?.sort) params.set("sort", opts.sort);
+		if (opts?.cursor) params.set("cursor", opts.cursor);
+		if (opts?.limit) params.set("limit", String(opts.limit));
+
+		const qs = params.toString();
+		const url = `${this.baseUrl}/api/v1/themes${qs ? `?${qs}` : ""}`;
+		return this.fetchJson<MarketplaceThemeSearchResult>(url);
+	}
+
+	async getTheme(id: string): Promise<MarketplaceThemeDetail> {
+		const url = `${this.baseUrl}/api/v1/themes/${encodeURIComponent(id)}`;
+		return this.fetchJson<MarketplaceThemeDetail>(url);
+	}
+
+	private async fetchJson<T>(url: string): Promise<T> {
+		let response: Response;
+		try {
+			response = await fetch(url, {
+				headers: { Accept: "application/json" },
+			});
+		} catch (err) {
+			throw new MarketplaceUnavailableError(err);
+		}
+
+		if (!response.ok) {
+			let errorMessage = `Marketplace request failed: ${response.status}`;
+			try {
+				const body: { error?: string } = await response.json();
+				if (body.error) errorMessage = body.error;
+			} catch {
+				// use default message
+			}
+			throw new MarketplaceError(errorMessage, response.status);
+		}
+
+		const data: T = await response.json();
+		return data;
+	}
+}
+
+// ── Bundle extraction ──────────────────────────────────────────────
+
+/**
+ * Extract manifest + code files from a tarball.
+ *
+ * The tarball is a gzipped tar archive containing:
+ * - manifest.json
+ * - backend.js
+ * - admin.js (optional)
+ *
+ * We use a minimal tar parser since we only need to read a few small files.
+ */
+async function extractBundle(tarballBytes: Uint8Array): Promise<PluginBundle> {
+	// Decompress fully into memory first, then parse the tar.
+	// Passing a pipeThrough() stream directly to unpackTar causes a backpressure
+	// deadlock in workerd: the tar decoder's body-stream pull() needs more
+	// decompressed data, but the upstream pipe is stalled waiting for the
+	// decoder's writable side to drain — a circular dependency.
+	const decompressedStream = new ReadableStream<Uint8Array>({
+		start(controller) {
+			controller.enqueue(tarballBytes);
+			controller.close();
+		},
+	}).pipeThrough(createGzipDecoder());
+
+	// Collect decompressed bytes fully before parsing
+	const decompressedBuf = await new Response(decompressedStream).arrayBuffer();
+	const decompressedBytes = new Uint8Array(decompressedBuf);
+	const decompressed = new ReadableStream<Uint8Array>({
+		start(controller) {
+			controller.enqueue(decompressedBytes);
+			controller.close();
+		},
+	});
+
+	const entries = await unpackTar(decompressed);
+
+	const decoder = new TextDecoder();
+	const files = new Map<string, string>();
+	for (const entry of entries) {
+		if (entry.data && entry.header.type === "file") {
+			// Strip leading ./ prefix that tar tools commonly add
+			const name = entry.header.name.replace(LEADING_DOT_SLASH, "");
+			files.set(name, decoder.decode(entry.data));
+		}
+	}
+
+	const manifestJson = files.get("manifest.json");
+	const backendCode = files.get("backend.js");
+
+	if (!manifestJson) {
+		throw new MarketplaceError(
+			"Invalid bundle: missing manifest.json",
+			undefined,
+			"INVALID_BUNDLE",
+		);
+	}
+	if (!backendCode) {
+		throw new MarketplaceError("Invalid bundle: missing backend.js", undefined, "INVALID_BUNDLE");
+	}
+
+	let manifest: PluginManifest;
+	try {
+		const parsed: unknown = JSON.parse(manifestJson);
+		const result = pluginManifestSchema.safeParse(parsed);
+		if (!result.success) {
+			throw new MarketplaceError(
+				"Invalid bundle: manifest.json failed validation",
+				undefined,
+				"INVALID_BUNDLE",
+			);
+		}
+		// Elements are validated as unknown[] by Zod; cast to PluginManifest
+		// for the Element[] type (Block Kit validation happens at render time).
+		// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- Zod types elements as unknown[]; Element type validated at render time
+		manifest = result.data as unknown as PluginManifest;
+	} catch (err) {
+		if (err instanceof MarketplaceError) throw err;
+		throw new MarketplaceError(
+			"Invalid bundle: malformed manifest.json",
+			undefined,
+			"INVALID_BUNDLE",
+		);
+	}
+
+	// Compute SHA-256 checksum of the tarball for verification
+	// eslint-disable-next-line typescript-eslint(no-unsafe-type-assertion) -- Uint8Array is a valid BufferSource at runtime; TS lib mismatch
+	const hashBuffer = await crypto.subtle.digest("SHA-256", tarballBytes as unknown as BufferSource);
+	const hashArray = new Uint8Array(hashBuffer);
+	const checksum = Array.from(hashArray, (b) => b.toString(16).padStart(2, "0")).join("");
+
+	return {
+		manifest,
+		backendCode,
+		adminCode: files.get("admin.js"),
+		checksum,
+	};
+}
+
+// ── Helpers ────────────────────────────────────────────────────────
+
+/** Generate a stable non-identifying site hash (best-effort) */
+async function generateSiteHash(): Promise<string> {
+	// Use a timestamp-based approach since we can't reliably get the origin
+	// in all contexts (Workers, Node, etc.)
+	const seed = `emdash-${Date.now()}`;
+	try {
+		const hash = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(seed));
+		const arr = new Uint8Array(hash);
+		return Array.from(arr.slice(0, 8), (b) => b.toString(16).padStart(2, "0")).join("");
+	} catch {
+		// Fallback for environments without crypto.subtle
+		return Math.random().toString(36).slice(2, 18);
+	}
+}
+
+// ── Factory ────────────────────────────────────────────────────────
+
+/**
+ * Create a MarketplaceClient for the given marketplace URL.
+ *
+ * @param baseUrl - The marketplace API base URL (e.g. "https://marketplace.emdashcms.com")
+ */
+export function createMarketplaceClient(baseUrl: string): MarketplaceClient {
+	return new MarketplaceClientImpl(baseUrl);
+}