@crewhaus/plugin-sdk 0.1.0

package/README.md

@@ -0,0 +1,98 @@
+# `@crewhaus/plugin-sdk`
+
+Typed surface for third-party Studio plugins. A plugin is a single TS module exporting `definePlugin({...})`; [studio-server](../studio-server/) lazy-loads them from `~/.crewhaus/plugins/<name>/index.ts` at boot.
+
+## Try it
+
+```bash
+cd plugin-sdk
+bun install
+bun run start
+# → defines a sample plugin, validates it, runs permission probes:
+#   ALLOW  fs read:./data/foo.json
+#   DENY   fs read:./secrets/key
+#   ALLOW  net fetch:https://api.example.com/v1/users
+#   DENY   net fetch:https://malicious.com/
+```
+
+## Author a plugin
+
+Create `~/.crewhaus/plugins/my-plugin/index.ts`:
+
+```typescript
+import { definePlugin } from "@crewhaus/plugin-sdk";
+
+export default definePlugin({
+  name: "my-plugin",
+  version: "0.1.0",
+  description: "Adds a custom side-pane to the studio.",
+
+  hooks: {
+    onSpecLoad(spec) {
+      // spec: { name, target, raw }
+    },
+    onTraceEvent(event) {
+      // event: { kind, ... } — fires for every SSE event
+    },
+    onEvalSampleRendered(sample) {
+      // sample: { id, passed, ... }
+    },
+  },
+
+  panes: [
+    {
+      id: "my-pane",
+      title: "My Pane",
+      html: "<div>Hello from my plugin</div>",
+    },
+  ],
+
+  permissions: {
+    fs: ["read:~/.crewhaus/plugins/my-plugin/data/**"],
+    net: ["fetch:https://api.example.com/**"],
+  },
+});
+```
+
+`definePlugin` validates the definition (`name`/`version` required, pane `id`s unique, permission entries prefixed with `read:` or `fetch:`) and freezes it. studio-server discovers the file when its `/api/plugins` endpoint scans `pluginRoot`.
+
+## Permissions
+
+A plugin declares exactly which filesystem paths and network origins it needs:
+
+```typescript
+permissions: {
+  fs: ["read:./data/**", "read:~/.crewhaus/plugins/my-plugin/cache/**"],
+  net: ["fetch:https://api.example.com/**", "fetch:https://*.example.com/**"],
+}
+```
+
+Patterns are minimatch-style globs (`**` recursive, `*` single-segment). Empty or absent permissions = **fail-closed** (deny all). The runtime gates each I/O attempt with `isFsAllowed(perms, path)` and `isNetAllowed(perms, url)`.
+
+> v0 enforces the filesystem allowlist at plugin-load via [`assertPluginPathsStaySandboxed`](./src/index.ts) (rejects `file://` URLs in pane HTML that escape the sandbox root). Full script isolation (worker / QuickJS) lands in a follow-up.
+
+## API surface
+
+| Export | Kind | Summary |
+|---|---|---|
+| `definePlugin(def)` | function | validates + freezes a plugin definition |
+| `assertPluginPathsStaySandboxed(plugin, root)` | function | throws if any pane HTML embeds a `file://` URL outside `root` |
+| `isFsAllowed(perms, path)` | function | true iff `path` matches an `fs: ["read:<glob>"]` entry |
+| `isNetAllowed(perms, url)` | function | true iff `url` matches a `net: ["fetch:<glob>"]` entry |
+| `validatePermissions(perms)` | function | structural check; throws `PluginSdkError` on bad prefixes |
+| `PluginSdkError` | class | thrown for any plugin-author mistake |
+| `StudioPluginDefinition` | type | what `definePlugin` accepts/returns |
+| `StudioPluginHooks` | type | `onSpecLoad`, `onTraceEvent`, `onEvalSampleRendered` |
+| `StudioPluginPane` | type | `{ id, title, html }` |
+| `PluginPermissions` | type | `{ fs?: string[], net?: string[] }` |
+
+## Pairs with
+
+- [studio-server](../studio-server/) — discovers plugins from `pluginRoot`, calls `assertPluginPathsStaySandboxed`, exposes `/api/plugins`
+- [studio-ui](../studio-ui/) — renders each plugin's `panes[]` in the Plugins tab
+
+## Related
+
+- Source: [src/index.ts](./src/index.ts), [src/scripts/start.ts](./src/scripts/start.ts)
+
+> Inside this workspace, resolves as `workspace:*`. Not yet on npm.

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@crewhaus/plugin-sdk",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Studio plugin SDK — typed surface for third-party panes / hooks / renderers (Section 26 Studio)",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "start": "bun src/scripts/start.ts",
+    "test": "bun test src"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Max Meier",
+    "email": "max@studiomax.io",
+    "url": "https://studiomax.io"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crewhaus/utilities.git",
+    "directory": "plugin-sdk"
+  },
+  "homepage": "https://github.com/crewhaus/utilities/tree/main/plugin-sdk#readme",
+  "bugs": {
+    "url": "https://github.com/crewhaus/utilities/issues"
+  },
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ]
+}

package/src/index.test.ts

@@ -0,0 +1,154 @@
+import { describe, expect, test } from "bun:test";
+import {
+  PluginSdkError,
+  assertPluginPathsStaySandboxed,
+  definePlugin,
+  isFsAllowed,
+  isNetAllowed,
+} from "./index.js";
+
+describe("definePlugin (T1)", () => {
+  test("returns a frozen plugin definition with the supplied fields", () => {
+    const p = definePlugin({
+      name: "fixture",
+      version: "0.0.1",
+      panes: [{ id: "main", title: "Hello", html: "<div>Hello from plugin</div>" }],
+    });
+    expect(p.name).toBe("fixture");
+    expect(p.version).toBe("0.0.1");
+    expect(p.panes?.[0]?.title).toBe("Hello");
+    expect(Object.isFrozen(p)).toBe(true);
+  });
+
+  test("rejects empty name / version", () => {
+    expect(() => definePlugin({ name: "", version: "1" })).toThrow(PluginSdkError);
+    expect(() => definePlugin({ name: "x", version: "" })).toThrow(PluginSdkError);
+  });
+
+  test("rejects duplicate pane ids within a plugin", () => {
+    expect(() =>
+      definePlugin({
+        name: "p",
+        version: "1",
+        panes: [
+          { id: "a", title: "A", html: "" },
+          { id: "a", title: "A2", html: "" },
+        ],
+      }),
+    ).toThrow(/duplicate pane id "a"/);
+  });
+
+  test("hooks pass through verbatim and are callable", () => {
+    let calls = 0;
+    const p = definePlugin({
+      name: "p",
+      version: "1",
+      hooks: {
+        onTraceEvent: () => {
+          calls += 1;
+        },
+      },
+    });
+    p.hooks?.onTraceEvent?.({ kind: "x" });
+    expect(calls).toBe(1);
+  });
+});
+
+describe("assertPluginPathsStaySandboxed (T8 — sandbox isolation)", () => {
+  test("allows file:// URLs inside the sandbox root", () => {
+    const p = definePlugin({
+      name: "p",
+      version: "1",
+      panes: [
+        {
+          id: "x",
+          title: "x",
+          html: '<a href="file:///home/u/.crewhaus/plugins/p/asset.png">a</a>',
+        },
+      ],
+    });
+    expect(() => assertPluginPathsStaySandboxed(p, "/home/u/.crewhaus/plugins/p/")).not.toThrow();
+  });
+
+  test("rejects file:// URLs outside the sandbox root", () => {
+    const p = definePlugin({
+      name: "p",
+      version: "1",
+      panes: [{ id: "x", title: "x", html: '<img src="file:///etc/passwd" />' }],
+    });
+    expect(() => assertPluginPathsStaySandboxed(p, "/home/u/.crewhaus/plugins/p/")).toThrow(
+      /outside its sandbox root/,
+    );
+  });
+
+  test("plugin with no panes is a no-op", () => {
+    const p = definePlugin({ name: "p", version: "1" });
+    expect(() => assertPluginPathsStaySandboxed(p, "/home/u/.crewhaus/plugins/p/")).not.toThrow();
+  });
+});
+
+describe("plugin-sdk v1 — Section 31 content sandbox (T8)", () => {
+  test("definePlugin validates the permissions schema", () => {
+    expect(() =>
+      definePlugin({
+        name: "p",
+        version: "1",
+        permissions: { fs: ["this-is-not-prefixed"] },
+      }),
+    ).toThrow(PluginSdkError);
+    expect(() =>
+      definePlugin({
+        name: "p",
+        version: "1",
+        permissions: { net: ["this-is-not-prefixed"] },
+      }),
+    ).toThrow(PluginSdkError);
+  });
+
+  test("isFsAllowed: empty permissions = fail-closed", () => {
+    expect(isFsAllowed(undefined, "/etc/passwd")).toBe(false);
+    expect(isFsAllowed({}, "/etc/passwd")).toBe(false);
+  });
+
+  test("isFsAllowed: sandbox-relative read pattern allows matching paths", () => {
+    const perms = { fs: ["read:/sandbox/data/**"] };
+    expect(isFsAllowed(perms, "/sandbox/data/file.json")).toBe(true);
+    expect(isFsAllowed(perms, "/sandbox/data/nested/file.json")).toBe(true);
+    expect(isFsAllowed(perms, "/etc/passwd")).toBe(false);
+  });
+
+  test("isFsAllowed: blocks /etc/passwd outside sandbox", () => {
+    const perms = { fs: ["read:/sandbox/**"] };
+    expect(isFsAllowed(perms, "/etc/passwd")).toBe(false);
+  });
+
+  test("isNetAllowed: empty permissions = fail-closed", () => {
+    expect(isNetAllowed(undefined, "https://example.com/x")).toBe(false);
+  });
+
+  test("isNetAllowed: fetch glob honored", () => {
+    const perms = { net: ["fetch:https://api.example.com/**"] };
+    expect(isNetAllowed(perms, "https://api.example.com/v1/users")).toBe(true);
+    expect(isNetAllowed(perms, "https://exfil.example.com/x")).toBe(false);
+  });
+
+  test("isNetAllowed: wildcard subdomain", () => {
+    const perms = { net: ["fetch:https://*.example.com/**"] };
+    expect(isNetAllowed(perms, "https://api.example.com/v1/x")).toBe(true);
+    expect(isNetAllowed(perms, "https://other.example.com/x")).toBe(true);
+    expect(isNetAllowed(perms, "https://malicious.com/x")).toBe(false);
+  });
+
+  test("plugin retains its declared permissions", () => {
+    const plugin = definePlugin({
+      name: "p",
+      version: "1",
+      permissions: {
+        fs: ["read:./local/**"],
+        net: ["fetch:https://api.example.com/**"],
+      },
+    });
+    expect(plugin.permissions?.fs?.[0]).toBe("read:./local/**");
+    expect(plugin.permissions?.net?.[0]).toBe("fetch:https://api.example.com/**");
+  });
+});

package/src/index.ts

@@ -0,0 +1,218 @@
+/**
+ * Catalog F5 `plugin-sdk` — Section 26 Studio.
+ *
+ * Typed surface for third-party studio plugins. A plugin is a single
+ * TS module exporting `definePlugin({...})`; the studio-server
+ * lazy-loads them from `~/.crewhaus/plugins/<name>/index.ts` at boot
+ * (or on hot-reload).
+ *
+ * v0 hooks:
+ *   - `onSpecLoad(spec)`           — observer; can return a side-pane
+ *                                    contribution to inject into the UI
+ *   - `onTraceEvent(event)`        — observer; called for every event
+ *                                    streamed over SSE
+ *   - `onEvalSampleRendered(sample)` — observer; called when an eval
+ *                                    sample is being prepared for the
+ *                                    UI panel
+ *
+ * v0 contributions: a plugin can declare `panes` — UI tabs the studio-
+ * ui adds to its sidebar — defined as `{ id, title, html }`. The HTML
+ * is rendered as innerHTML inside an iframe-shaped container; v0 ships
+ * a path-based sandbox (file-system reads outside `~/.crewhaus/plugins/
+ * <self>/` are rejected at load-time via `loadPlugin`'s allowlist) but
+ * NOT script isolation (deferred — proper isolation requires a worker
+ * or QuickJS sandbox).
+ */
+import { CrewhausError } from "@crewhaus/errors";
+
+export class PluginSdkError extends CrewhausError {
+  override readonly name = "PluginSdkError";
+  constructor(message: string, cause?: unknown) {
+    super("config", message, cause);
+  }
+}
+
+export type StudioPluginPane = {
+  readonly id: string;
+  readonly title: string;
+  /**
+   * Static HTML the studio-ui injects into the pane's container. Plugins
+   * that want dynamic behaviour can include a <script> tag — but see the
+   * sandbox notes above.
+   */
+  readonly html: string;
+};
+
+export type StudioPluginHooks = {
+  /** Called when the studio loads a spec for editing/inspection. */
+  onSpecLoad?(spec: { name: string; target: string; raw: string }): void;
+  /** Called for every TraceEvent streamed over SSE for a live run. */
+  onTraceEvent?(event: { kind: string; [k: string]: unknown }): void;
+  /** Called when an eval sample is being prepared for the UI panel. */
+  onEvalSampleRendered?(sample: { id: string; passed: boolean; [k: string]: unknown }): void;
+};
+
+/**
+ * Section 31 — declared permissions schema. Plugins state up-front
+ * exactly which filesystem paths they need to read (relative to their
+ * sandbox root) and which network origins they can fetch. Runtime
+ * enforces the allow-list — any I/O outside the declared scope is
+ * blocked by the sandbox.
+ *
+ * Format:
+ *   fs: ["read:~/.crewhaus/plugins/<self>/data/**", "read:./fixtures/**"]
+ *   net: ["fetch:https://api.example.com/**", "fetch:https://*.example.com/**"]
+ *
+ * Patterns are minimatch-style globs against either filesystem paths
+ * (relative to the plugin's sandbox root) or URL prefixes. The runtime
+ * evaluator (`isFsAllowed` / `isNetAllowed`) is pure-string and
+ * deterministic so callers can audit exactly what each plugin can do
+ * before instantiating its sandbox.
+ */
+export type PluginPermissions = {
+  readonly fs?: ReadonlyArray<string>;
+  readonly net?: ReadonlyArray<string>;
+};
+
+export type StudioPluginDefinition = {
+  readonly name: string;
+  /** Semver-shaped version string. Studio renders this in the plugins panel. */
+  readonly version: string;
+  readonly hooks?: StudioPluginHooks;
+  readonly panes?: ReadonlyArray<StudioPluginPane>;
+  /**
+   * Optional one-line description shown in the plugins panel.
+   */
+  readonly description?: string;
+  /**
+   * Section 31 — declared permissions allow-list. Optional; absent
+   * means "no fs / no net access" (fail-closed).
+   */
+  readonly permissions?: PluginPermissions;
+};
+
+/**
+ * Type-only helper. Plugins call:
+ *   export default definePlugin({ name, version, hooks, panes });
+ */
+export function definePlugin(def: StudioPluginDefinition): StudioPluginDefinition {
+  if (typeof def.name !== "string" || def.name.length === 0) {
+    throw new PluginSdkError("definePlugin: `name` is required");
+  }
+  if (typeof def.version !== "string" || def.version.length === 0) {
+    throw new PluginSdkError("definePlugin: `version` is required");
+  }
+  const ids = new Set<string>();
+  for (const p of def.panes ?? []) {
+    if (ids.has(p.id)) {
+      throw new PluginSdkError(`definePlugin "${def.name}": duplicate pane id "${p.id}"`);
+    }
+    ids.add(p.id);
+  }
+  // Section 31 — validate the declared permissions schema.
+  validatePermissions(def.permissions);
+  return Object.freeze({ ...def });
+}
+
+/**
+ * Path-sandbox guard: a plugin loader is given a root directory
+ * (`~/.crewhaus/plugins/<self>/`) and must resolve all imports inside
+ * that root. This helper is exposed so the loader can reject a plugin
+ * whose `definePlugin({...})` body smuggles file-path strings outside
+ * the sandbox boundary (e.g. an exfil attempt via a pane's html).
+ *
+ * v0 only checks the plugin's declared `panes[].html` for `file://`
+ * URLs that escape the sandbox; full content-sandbox isolation lands
+ * in a follow-up.
+ */
+export function assertPluginPathsStaySandboxed(
+  plugin: StudioPluginDefinition,
+  sandboxRoot: string,
+): void {
+  const root = sandboxRoot.endsWith("/") ? sandboxRoot.slice(0, -1) : sandboxRoot;
+  for (const pane of plugin.panes ?? []) {
+    const fileUrls = pane.html.match(/file:\/\/\S+/g) ?? [];
+    for (const u of fileUrls) {
+      const path = u.replace(/^file:\/\//, "");
+      if (!path.startsWith(root)) {
+        throw new PluginSdkError(
+          `plugin "${plugin.name}" pane "${pane.id}" references file:// path outside its sandbox root: ${path}`,
+        );
+      }
+    }
+  }
+}
+
+/**
+ * Section 31 — content-sandbox runtime checks. The two helpers below
+ * accept a plugin's declared permissions and return whether a given
+ * fs path / network URL is permitted. The runtime caller wires this
+ * into the actual sandbox boundary (Web Worker postMessage gate for UI
+ * plugins, VM2-style realm for server plugins) so attempts to read
+ * `/etc/passwd` or fetch `https://exfil.example.com/...` are blocked
+ * at the sandbox edge.
+ *
+ * Pattern matching:
+ *  - `read:<path-glob>` — matches absolute or sandbox-relative paths.
+ *    Globs use `**` for recursive and `*` for single-segment.
+ *  - `fetch:<url-glob>` — matches request URLs by prefix + glob.
+ *
+ * Empty / undefined permissions = fail-closed (deny all).
+ */
+export function isFsAllowed(perms: PluginPermissions | undefined, path: string): boolean {
+  if (!perms?.fs) return false;
+  const patterns = perms.fs
+    .filter((p) => p.startsWith("read:"))
+    .map((p) => p.slice("read:".length));
+  return patterns.some((pat) => globMatch(pat, path));
+}
+
+export function isNetAllowed(perms: PluginPermissions | undefined, url: string): boolean {
+  if (!perms?.net) return false;
+  const patterns = perms.net
+    .filter((p) => p.startsWith("fetch:"))
+    .map((p) => p.slice("fetch:".length));
+  return patterns.some((pat) => globMatch(pat, url));
+}
+
+/**
+ * Tiny minimatch shim — supports `**` (recursive), `*` (segment), and
+ * literal-character matching. Sufficient for the plugin-permission
+ * use case; for a more sophisticated patterning need we'd swap in
+ * minimatch proper.
+ */
+function globMatch(pattern: string, value: string): boolean {
+  // Convert glob to a regex anchored at start + end.
+  const escaped = pattern
+    .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+    // ** must come BEFORE * — otherwise "*" replaces inside "**" first.
+    .replace(/\*\*/g, "__GLOB_DOUBLE_STAR__")
+    .replace(/\*/g, "[^/]*")
+    .replace(/__GLOB_DOUBLE_STAR__/g, ".*");
+  const re = new RegExp(`^${escaped}$`);
+  return re.test(value);
+}
+
+/**
+ * Section 31 — assert a plugin's declared permissions match the
+ * actually-needed scope. Used at plugin-load time so a plugin that
+ * declares overly broad permissions fails to load.
+ *
+ * v0 just runs structural validation (fs entries start with `read:`,
+ * net entries start with `fetch:`); a follow-up adds policy-engine
+ * integration so admins can refuse plugins whose declared net allow-
+ * list includes broad wildcards.
+ */
+export function validatePermissions(perms: PluginPermissions | undefined): void {
+  if (!perms) return;
+  for (const f of perms.fs ?? []) {
+    if (!f.startsWith("read:")) {
+      throw new PluginSdkError(`fs permission "${f}" must start with "read:"`);
+    }
+  }
+  for (const n of perms.net ?? []) {
+    if (!n.startsWith("fetch:")) {
+      throw new PluginSdkError(`net permission "${n}" must start with "fetch:"`);
+    }
+  }
+}

package/src/scripts/start.ts

@@ -0,0 +1,58 @@
+/**
+ * `bun run start` entry point for `@crewhaus/plugin-sdk`.
+ *
+ * Defines a sample studio plugin via `definePlugin`, validates its
+ * permissions, and exercises the `isFsAllowed` / `isNetAllowed`
+ * decision functions against a few representative paths/URLs.
+ */
+import {
+  definePlugin,
+  isFsAllowed,
+  isNetAllowed,
+  validatePermissions,
+} from "../index";
+
+const demo = definePlugin({
+  name: "demo-plugin",
+  version: "0.1.0",
+  description: "Sample plugin exercising the SDK surface.",
+  hooks: {
+    onSpecLoad(spec) {
+      void spec; // observer
+    },
+    onTraceEvent(event) {
+      void event; // observer
+    },
+  },
+  panes: [
+    {
+      id: "demo-pane",
+      title: "Demo Pane",
+      html: "<div>Hello from demo-plugin</div>",
+    },
+  ],
+  permissions: {
+    fs: ["read:./data/**", "read:~/.crewhaus/plugins/demo-plugin/cache/**"],
+    net: ["fetch:https://api.example.com/**", "fetch:https://*.example.com/**"],
+  },
+});
+
+validatePermissions(demo.permissions);
+
+process.stdout.write(`✓ definePlugin() returned a frozen manifest for "${demo.name}"\n`);
+process.stdout.write(`  version:     ${demo.version}\n`);
+process.stdout.write(`  description: ${demo.description}\n`);
+process.stdout.write(`  hooks:       ${Object.keys(demo.hooks ?? {}).join(", ") || "(none)"}\n`);
+process.stdout.write(`  panes:       ${demo.panes?.map((p) => p.id).join(", ") ?? "(none)"}\n`);
+process.stdout.write(`  permissions: fs=${demo.permissions?.fs?.length ?? 0}, net=${demo.permissions?.net?.length ?? 0}\n`);
+
+process.stdout.write(`\nPermission probes:\n`);
+const checks: ReadonlyArray<readonly [string, () => boolean]> = [
+  ["fs read:./data/foo.json", () => isFsAllowed(demo.permissions, "./data/foo.json")],
+  ["fs read:./secrets/key", () => isFsAllowed(demo.permissions, "./secrets/key")],
+  ["net fetch:https://api.example.com/v1/users", () => isNetAllowed(demo.permissions, "https://api.example.com/v1/users")],
+  ["net fetch:https://malicious.com/", () => isNetAllowed(demo.permissions, "https://malicious.com/")],
+];
+for (const [label, fn] of checks) {
+  process.stdout.write(`  ${fn() ? "ALLOW" : "DENY "}  ${label}\n`);
+}