@abraca/plugin 2.3.0

package/src/host.ts

@@ -0,0 +1,221 @@
+/**
+ * `PluginHost` — capability-guarded wrapper around the browser globals
+ * a plugin is allowed to call. Each guard consults the plugin's
+ * manifest before forwarding to the underlying API. A plugin that
+ * declared `network:api.example.com` can only `fetch` against
+ * `api.example.com`; a plugin without `clipboard:write` cannot write
+ * the clipboard; etc.
+ *
+ * Phase 1 contract: this is opt-in. Plugins that import `createPluginHost`
+ * and use its members get the gate for free. Plugins that grab
+ * `globalThis.fetch` directly bypass the gate — sandboxing (iframe / Web
+ * Worker / Wasm) lands in Phase F.2 and closes that loophole.
+ *
+ * The `CapabilityDenied` error class lets hosts (and tests) distinguish
+ * policy failures from other runtime errors.
+ */
+
+import type { PluginCapability, PluginManifest } from "./manifest.ts";
+
+// ── Errors ────────────────────────────────────────────────────────────────────
+
+/**
+ * Thrown when a plugin tries to use an API it didn't declare in its
+ * manifest. Distinct from runtime failures (network 500, file not found,
+ * etc.) so the host can show the user "the plugin tried to do X without
+ * permission" instead of a generic error.
+ */
+export class CapabilityDenied extends Error {
+	readonly capability: PluginCapability | string;
+	readonly pluginId: string;
+
+	constructor(pluginId: string, capability: PluginCapability | string, detail?: string) {
+		super(
+			`plugin '${pluginId}' is not authorised to use '${capability}'${detail ? ` (${detail})` : ""}`,
+		);
+		this.name = "CapabilityDenied";
+		this.capability = capability;
+		this.pluginId = pluginId;
+	}
+}
+
+// ── Host shape ────────────────────────────────────────────────────────────────
+
+/** Subset of the global `fetch` signature the host exposes. */
+export type GuardedFetch = (
+	input: RequestInfo | URL,
+	init?: RequestInit,
+) => Promise<Response>;
+
+/** Subset of `navigator.clipboard` the host exposes. */
+export interface GuardedClipboard {
+	readText(): Promise<string>;
+	writeText(text: string): Promise<void>;
+}
+
+/** Permission-aware desktop notification. */
+export interface GuardedNotifications {
+	show(title: string, options?: NotificationOptions): Promise<void>;
+}
+
+/**
+ * Everything a plugin is allowed to touch through the host contract.
+ * Each plugin gets its own instance via `createPluginHost(manifest)`.
+ */
+export interface PluginHost {
+	readonly pluginId: string;
+	readonly capabilities: ReadonlySet<PluginCapability>;
+	fetch: GuardedFetch;
+	clipboard: GuardedClipboard;
+	notifications: GuardedNotifications;
+	/** Test whether a capability is granted without invoking the wrapped API. */
+	can(capability: PluginCapability | string): boolean;
+}
+
+// ── Constructor ───────────────────────────────────────────────────────────────
+
+export interface PluginHostOptions {
+	/**
+	 * Override the underlying `fetch`. Tests inject a stub here; production
+	 * hosts leave this unset and use the global.
+	 */
+	fetch?: typeof fetch;
+	/** Override `navigator.clipboard`. */
+	clipboard?: {
+		readText?(): Promise<string>;
+		writeText?(text: string): Promise<void>;
+	};
+	/**
+	 * Override the host's notification surface. The default uses the
+	 * browser's `Notification` API — fine for web hosts; native hosts
+	 * (Tauri, Electron) inject their own.
+	 */
+	showNotification?(title: string, options?: NotificationOptions): Promise<void>;
+}
+
+/**
+ * Build a `PluginHost` from a manifest. The set of granted capabilities
+ * is `manifest.capabilities.required ∪ optional`; runtime gates check
+ * membership before forwarding to the underlying API.
+ *
+ * Network capabilities support host patterns:
+ *   - `network`           — any host
+ *   - `network:api.foo.io` — exact match
+ *   - `network:*.foo.io`   — wildcard subdomain match
+ *   - `network:foo.io,bar.io` — comma-separated list
+ */
+export function createPluginHost(
+	manifest: Pick<PluginManifest, "id" | "capabilities">,
+	options: PluginHostOptions = {},
+): PluginHost {
+	const granted = new Set<PluginCapability>([
+		...(manifest.capabilities.required ?? []),
+		...(manifest.capabilities.optional ?? []),
+	]);
+	const pluginId = manifest.id;
+
+	const can = (cap: PluginCapability | string): boolean => granted.has(cap as PluginCapability);
+
+	const guardedFetch: GuardedFetch = async (input, init) => {
+		const url = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
+		const host = extractHost(url);
+		if (!host) {
+			throw new CapabilityDenied(pluginId, "network", "could not parse URL host");
+		}
+		if (!matchesNetworkCapability(granted, host)) {
+			throw new CapabilityDenied(
+				pluginId,
+				`network:${host}`,
+				"declare it in capabilities.required or capabilities.optional",
+			);
+		}
+		const real = options.fetch ?? globalThis.fetch;
+		if (!real) throw new Error("fetch is not available in this runtime");
+		return real(input, init);
+	};
+
+	const guardedClipboard: GuardedClipboard = {
+		async readText() {
+			if (!granted.has("clipboard:read")) {
+				throw new CapabilityDenied(pluginId, "clipboard:read");
+			}
+			if (options.clipboard?.readText) return options.clipboard.readText();
+			if (typeof navigator !== "undefined" && navigator.clipboard?.readText) {
+				return navigator.clipboard.readText();
+			}
+			throw new Error("clipboard.readText is not available in this runtime");
+		},
+		async writeText(text: string) {
+			if (!granted.has("clipboard:write")) {
+				throw new CapabilityDenied(pluginId, "clipboard:write");
+			}
+			if (options.clipboard?.writeText) return options.clipboard.writeText(text);
+			if (typeof navigator !== "undefined" && navigator.clipboard?.writeText) {
+				return navigator.clipboard.writeText(text);
+			}
+			throw new Error("clipboard.writeText is not available in this runtime");
+		},
+	};
+
+	const guardedNotifications: GuardedNotifications = {
+		async show(title: string, opts?: NotificationOptions) {
+			if (!granted.has("notifications:show")) {
+				throw new CapabilityDenied(pluginId, "notifications:show");
+			}
+			if (options.showNotification) return options.showNotification(title, opts);
+			if (typeof Notification !== "undefined") {
+				new Notification(title, opts);
+				return;
+			}
+			throw new Error("notifications are not available in this runtime");
+		},
+	};
+
+	return {
+		pluginId,
+		capabilities: granted,
+		fetch: guardedFetch,
+		clipboard: guardedClipboard,
+		notifications: guardedNotifications,
+		can,
+	};
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function extractHost(rawUrl: string): string | null {
+	try {
+		return new URL(rawUrl, "http://placeholder").host;
+	}
+	catch {
+		return null;
+	}
+}
+
+/**
+ * Network capability matcher — `network`, `network:exact.host`,
+ * `network:*.wildcard.host`, `network:a,b,c` comma-list. Exported so
+ * the iframe sandbox can reuse the same rules without forking the
+ * vocabulary.
+ */
+export function matchesNetworkCapability(granted: ReadonlySet<PluginCapability>, host: string): boolean {
+	if (granted.has("network")) return true;
+	for (const cap of granted) {
+		if (!cap.startsWith("network:")) continue;
+		const patterns = cap.slice("network:".length).split(",");
+		for (const pattern of patterns) {
+			if (matchesHostPattern(pattern.trim(), host)) return true;
+		}
+	}
+	return false;
+}
+
+function matchesHostPattern(pattern: string, host: string): boolean {
+	if (!pattern) return false;
+	if (pattern === host) return true;
+	if (pattern.startsWith("*.")) {
+		const suffix = pattern.slice(2);
+		return host === suffix || host.endsWith(`.${suffix}`);
+	}
+	return false;
+}

package/src/index.ts

@@ -0,0 +1,67 @@
+/**
+ * `@abraca/plugin` — public surface.
+ *
+ * Shared types + registry runtime consumed by cou-shell and `@abraca/nuxt`.
+ * The package is types-and-class-only: no host imports, no React/Vue/Nuxt
+ * dependencies at runtime.
+ */
+
+export {
+	type AbraPlugin,
+	type AbraYDoc,
+	type AbraTiptapExtension,
+	type EditorPluginCtx,
+	type DragHandlePluginCtx,
+	type ClientPluginCtx,
+	type CommandPaletteCtx,
+	type MentionPluginCtx,
+	type RefLike,
+	type EditorRefLike,
+	type AbraMentionProvider,
+	type AbraMentionItem,
+	type AbraAwarenessContribution,
+	type AbraCommandItem,
+	type AbraNodePanelSlot,
+	type NodePanelCtx,
+	type AbraSettingsPanel,
+	type AbraKeyboardShortcut,
+	type CollaborationUser,
+	type RunnerCleanup,
+	type ServerRunnerDefinition,
+	type ServerRunnerContextBase,
+} from "./types.ts";
+
+export { PluginRegistry } from "./registry.ts";
+
+export {
+	type ExternalPluginEntry,
+	normalizePluginUrl,
+	isSafePluginUrl,
+} from "./source-spec.ts";
+
+export {
+	type PluginCapability,
+	type PluginManifestAuthor,
+	type PluginPricing,
+	type PluginVersionStatus,
+	type PluginManifestContributes,
+	type PluginManifest,
+	type PluginRegistryEntry,
+} from "./manifest.ts";
+
+export {
+	CapabilityDenied,
+	createPluginHost,
+	matchesNetworkCapability,
+	type PluginHost,
+	type PluginHostOptions,
+	type GuardedFetch,
+	type GuardedClipboard,
+	type GuardedNotifications,
+} from "./host.ts";
+
+export {
+	loadSandboxedPlugin,
+	type SandboxedPlugin,
+	type SandboxOptions,
+} from "./sandbox.ts";

package/src/manifest.ts

@@ -0,0 +1,173 @@
+/**
+ * Plugin manifest v1 — the declarative `manifest.json` colocated with a
+ * plugin's bundle. Hosts parse this before executing the bundle, and the
+ * registry server (Phase C) validates it server-side too.
+ *
+ * Phase A scope: types only. Zod validators + JSON Schema generation live
+ * in `@abraca/schema` (Phase B).
+ */
+
+/**
+ * Capability tokens declared by a plugin's manifest. The host enforces these
+ * at the plugin-host boundary — a plugin without `network:*` cannot `fetch()`,
+ * a plugin without `clipboard:write` cannot write the clipboard, etc.
+ *
+ * Phase 1 enforcement is contract-based (we wrap host APIs). Phase 4 adds
+ * Wasm / Web Worker / iframe sandboxing so the contract is enforced at the
+ * runtime boundary, not just the host-API boundary.
+ */
+export type PluginCapability =
+	/** Outbound HTTP — `network` (any host) or `network:<host>` (exact match, wildcards allowed). */
+	| `network${"" | `:${string}`}`
+	/** Filesystem reads — only meaningful in Tauri / native hosts. */
+	| "fs:read"
+	/** Filesystem writes — Tauri / native only. */
+	| "fs:write"
+	/** Read the clipboard. */
+	| "clipboard:read"
+	/** Write the clipboard. */
+	| "clipboard:write"
+	/** Read any Y.Doc the host has loaded. */
+	| "doc-read"
+	/** Mutate Y.Docs (transact_mut against the host's provider). */
+	| "doc-write"
+	/** Broadcast presence / awareness state. */
+	| "awareness"
+	/** Register an RPC v1 handler on the service runner. */
+	| "server-runner"
+	/** Contribute items to the global command palette. */
+	| "command-palette"
+	/** Contribute editor toolbar items. */
+	| "toolbar"
+	/** Contribute bubble-menu items (text selection). */
+	| "bubble-menu"
+	/** Contribute slash-command suggestion items. */
+	| "slash-command"
+	/** Contribute drag-handle items. */
+	| "drag-handle"
+	/** Register a page-type renderer with the given slug. */
+	| `page-type:${string}`
+	/** Send messages on the in-doc chat channel. */
+	| "chat:send"
+	/** Read in-doc chat history. */
+	| "chat:read"
+	/** Show user-visible notifications. */
+	| "notifications:show";
+
+export interface PluginManifestAuthor {
+	/** GitHub login. Identifies the author in the registry. */
+	github?: string;
+	/** Human-readable display name. */
+	name?: string;
+	url?: string;
+	email?: string;
+}
+
+/** Pricing label as defined in the registry — see registry docs for semantics. */
+export type PluginPricing = "free" | "optional" | "paid";
+
+/** Submission / publication status as exposed by the registry's catalog API. */
+export type PluginVersionStatus =
+	| "live"
+	| "pending"
+	| "rejected"
+	| "superseded";
+
+/** Declared contributions — the plugin's static claim about what it ships. */
+export interface PluginManifestContributes {
+	pageTypes?: readonly string[];
+	extensions?: readonly string[];
+	awarenessFields?: readonly string[];
+	serverRunners?: readonly string[];
+	commands?: readonly string[];
+	settingsPanels?: readonly string[];
+}
+
+/**
+ * The static manifest colocated with the plugin entry. Versioned via the
+ * top-level `manifestVersion` field — the only field guaranteed to exist
+ * verbatim across all manifest versions.
+ */
+export interface PluginManifest {
+	/** Schema version of this manifest format. Currently always `1`. */
+	manifestVersion: 1;
+
+	/** Unique lowercase-kebab slug. Stable across versions. */
+	id: string;
+
+	/** Display name. Falls back to `id`. */
+	name?: string;
+
+	/** Plugin version (semver). */
+	version: string;
+
+	/** Author / maintainer info. */
+	author: PluginManifestAuthor;
+
+	/** SPDX license identifier (e.g. `MIT`, `Apache-2.0`). */
+	license: string;
+
+	/** One- to two-sentence summary shown in browsers and scorecards. */
+	description: string;
+
+	/** Long-form description / changelog — markdown allowed. */
+	readme?: string;
+
+	homepage?: string;
+
+	/** `github:user/repo` shorthand or any URL. */
+	repository?: string;
+
+	/** Minimum Abracadabra SDK version required (semver range). */
+	minAbracadabraVersion?: string;
+
+	/** Path to the bundle entry, relative to the manifest. */
+	entry: string;
+
+	/**
+	 * SHA-256 of the bundle entry, hex-encoded. Verified by hosts before
+	 * `import()`. Mismatch → refuse to load.
+	 */
+	integrity: string;
+
+	/** Pricing tier as defined in the registry. */
+	pricing?: PluginPricing;
+
+	/** Screenshot paths (relative to manifest), shown on the detail page. */
+	screenshots?: readonly string[];
+
+	/** Free-form category tags for catalog filtering. */
+	categories?: readonly string[];
+
+	/** Required capabilities — host MUST grant these or refuse the install. */
+	capabilities: {
+		required: readonly PluginCapability[];
+		optional?: readonly PluginCapability[];
+	};
+
+	/** Declared contributions. Static check; verified against runtime registrations. */
+	contributes?: PluginManifestContributes;
+
+	/**
+	 * Peer dependencies the plugin expects the host to provide. Hosts publish
+	 * the versions they ship via `globalThis.__ABRACA_SHARED__`.
+	 */
+	peerDeps?: Record<string, string>;
+}
+
+/** Registry-decorated manifest — what the catalog API returns. */
+export interface PluginRegistryEntry {
+	manifest: PluginManifest;
+	/** Resolved bundle URL (R2 / jsDelivr / etc). */
+	artifactUrl: string;
+	/** Registry-side artifact hash, mirrors `manifest.integrity`. */
+	artifactSha256: string;
+	/** Status as seen by the registry. */
+	status: PluginVersionStatus;
+	publishedAt: string;
+	/**
+	 * Scorecard summary — `null` until the registry has scanned this version.
+	 * Concrete shape lives in `@abraca/schema` (Phase H).
+	 */
+	scorecard: unknown | null;
+}