@crewhaus/plugin-sdk 0.1.1 → 0.1.2

package/package.json

@@ -1,39 +1,37 @@
 {
   "name": "@crewhaus/plugin-sdk",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "type": "module",
-  "description": "Studio plugin SDK — typed surface for third-party panes / hooks / renderers (Section 26 Studio)",
+  "description": "Plugin SDK v2 — public typed surface for third-party tools / channels / models / graders / target backends, with manifest validation and Ed25519 signature verification (Section 41)",
   "main": "src/index.ts",
   "types": "src/index.ts",
   "exports": {
     ".": "./src/index.ts"
   },
   "scripts": {
-    "start": "bun src/scripts/start.ts",
     "test": "bun test src"
   },
+  "dependencies": {
+    "@crewhaus/errors": "0.1.2",
+    "@crewhaus/tool-catalog": "0.1.2"
+  },
   "license": "Apache-2.0",
   "author": {
     "name": "Max Meier",
-    "email": "max@studiomax.io",
-    "url": "https://studiomax.io"
+    "email": "max@crewhaus.ai",
+    "url": "https://crewhaus.ai"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/crewhaus/utilities.git",
-    "directory": "plugin-sdk"
+    "url": "git+https://github.com/crewhaus/factory.git",
+    "directory": "packages/plugin-sdk"
   },
-  "homepage": "https://github.com/crewhaus/utilities/tree/main/plugin-sdk#readme",
+  "homepage": "https://github.com/crewhaus/factory/tree/main/packages/plugin-sdk#readme",
   "bugs": {
-    "url": "https://github.com/crewhaus/utilities/issues"
+    "url": "https://github.com/crewhaus/factory/issues"
   },
   "publishConfig": {
-    "access": "restricted"
+    "access": "public"
   },
-  "files": [
-    "src",
-    "README.md",
-    "LICENSE",
-    "NOTICE"
-  ]
+  "files": ["src", "README.md", "LICENSE", "NOTICE"]
 }

package/src/index.test.ts

@@ -1,154 +1,237 @@
 import { describe, expect, test } from "bun:test";
 import {
   PluginSdkError,
-  assertPluginPathsStaySandboxed,
+  canonicalJson,
   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);
-  });
+  manifestPayloadForSigning,
+  validatePluginManifest,
+} from "./index";
 
-  test("rejects empty name / version", () => {
-    expect(() => definePlugin({ name: "", version: "1" })).toThrow(PluginSdkError);
-    expect(() => definePlugin({ name: "x", version: "" })).toThrow(PluginSdkError);
+describe("validatePluginManifest", () => {
+  test("accepts a minimal valid manifest", () => {
+    const m = validatePluginManifest({ name: "my-plugin", version: "1.2.3" });
+    expect(m.name).toBe("my-plugin");
+    expect(m.version).toBe("1.2.3");
   });
 
-  test("rejects duplicate pane ids within a plugin", () => {
+  test("accepts pre-release + build metadata in semver", () => {
     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);
+      validatePluginManifest({ name: "my-plugin", version: "1.2.3-beta.1+build.42" }),
+    ).not.toThrow();
   });
-});
 
-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 missing name", () => {
+    expect(() => validatePluginManifest({ version: "1.0.0" })).toThrow(PluginSdkError);
   });
 
-  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("rejects invalid name", () => {
+    expect(() => validatePluginManifest({ name: "MyPlugin", version: "1.0.0" })).toThrow(
+      PluginSdkError,
+    );
+    expect(() => validatePluginManifest({ name: "-leading", version: "1.0.0" })).toThrow(
+      PluginSdkError,
+    );
+    expect(() => validatePluginManifest({ name: "trailing-", version: "1.0.0" })).toThrow(
+      PluginSdkError,
+    );
+    expect(() => validatePluginManifest({ name: "1starts-with-digit", version: "1.0.0" })).toThrow(
+      PluginSdkError,
+    );
+  });
+
+  test("rejects non-semver version", () => {
+    expect(() => validatePluginManifest({ name: "ok-name", version: "v1.2.3" })).toThrow(
+      PluginSdkError,
+    );
+    expect(() => validatePluginManifest({ name: "ok-name", version: "1.2" })).toThrow(
+      PluginSdkError,
     );
   });
 
-  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();
+  test("validates engines.crewhaus when present", () => {
+    expect(() =>
+      validatePluginManifest({
+        name: "ok-name",
+        version: "1.0.0",
+        engines: { crewhaus: "^0.2.0" },
+      }),
+    ).not.toThrow();
+    expect(() =>
+      validatePluginManifest({
+        name: "ok-name",
+        version: "1.0.0",
+        engines: { crewhaus: 42 },
+      }),
+    ).toThrow(PluginSdkError);
   });
-});
 
-describe("plugin-sdk v1 — Section 31 content sandbox (T8)", () => {
-  test("definePlugin validates the permissions schema", () => {
+  test("validates permissions arrays are string arrays", () => {
+    expect(() =>
+      validatePluginManifest({
+        name: "ok-name",
+        version: "1.0.0",
+        permissions: { fs: ["read:./data/**"], net: ["fetch:https://api.example.com/**"] },
+      }),
+    ).not.toThrow();
     expect(() =>
-      definePlugin({
-        name: "p",
-        version: "1",
-        permissions: { fs: ["this-is-not-prefixed"] },
+      validatePluginManifest({
+        name: "ok-name",
+        version: "1.0.0",
+        permissions: { fs: [42] },
       }),
     ).toThrow(PluginSdkError);
     expect(() =>
-      definePlugin({
-        name: "p",
-        version: "1",
-        permissions: { net: ["this-is-not-prefixed"] },
+      validatePluginManifest({
+        name: "ok-name",
+        version: "1.0.0",
+        permissions: { tools: "Bash" }, // must be array
       }),
     ).toThrow(PluginSdkError);
   });
 
-  test("isFsAllowed: empty permissions = fail-closed", () => {
-    expect(isFsAllowed(undefined, "/etc/passwd")).toBe(false);
-    expect(isFsAllowed({}, "/etc/passwd")).toBe(false);
+  test("validates signature shape", () => {
+    const ok = {
+      name: "ok-name",
+      version: "1.0.0",
+      signature: {
+        algorithm: "ed25519",
+        publicKeyB64: "base64-data",
+        sigB64: "base64-sig",
+      },
+    };
+    expect(() => validatePluginManifest(ok)).not.toThrow();
   });
 
-  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("rejects non-ed25519 algorithms", () => {
+    expect(() =>
+      validatePluginManifest({
+        name: "ok-name",
+        version: "1.0.0",
+        signature: { algorithm: "rsa", publicKeyB64: "x", sigB64: "y" },
+      }),
+    ).toThrow(PluginSdkError);
   });
 
-  test("isFsAllowed: blocks /etc/passwd outside sandbox", () => {
-    const perms = { fs: ["read:/sandbox/**"] };
-    expect(isFsAllowed(perms, "/etc/passwd")).toBe(false);
+  test("rejects signature missing publicKeyB64 / sigB64", () => {
+    expect(() =>
+      validatePluginManifest({
+        name: "ok-name",
+        version: "1.0.0",
+        signature: { algorithm: "ed25519", publicKeyB64: "x" },
+      }),
+    ).toThrow(PluginSdkError);
   });
 
-  test("isNetAllowed: empty permissions = fail-closed", () => {
-    expect(isNetAllowed(undefined, "https://example.com/x")).toBe(false);
+  test("rejects non-object manifest", () => {
+    expect(() => validatePluginManifest(null)).toThrow(PluginSdkError);
+    expect(() => validatePluginManifest("not an object")).toThrow(PluginSdkError);
+    expect(() => validatePluginManifest(42)).toThrow(PluginSdkError);
   });
+});
 
-  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);
+describe("definePlugin", () => {
+  test("returns the input unchanged on success", () => {
+    const def = definePlugin({
+      name: "my-plugin",
+      version: "1.0.0",
+      description: "demo",
+    });
+    expect(def.name).toBe("my-plugin");
+    expect(def.description).toBe("demo");
   });
 
-  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("throws on invalid manifest", () => {
+    expect(() => definePlugin({ name: "MyPlugin", version: "1.0.0" } as never)).toThrow(
+      PluginSdkError,
+    );
   });
 
-  test("plugin retains its declared permissions", () => {
-    const plugin = definePlugin({
-      name: "p",
-      version: "1",
-      permissions: {
-        fs: ["read:./local/**"],
-        net: ["fetch:https://api.example.com/**"],
+  test("carries contribution types through", () => {
+    const def = definePlugin({
+      name: "my-plugin",
+      version: "1.0.0",
+      contributions: {
+        graders: [
+          {
+            id: "my-grader",
+            async grade() {
+              return { pass: true };
+            },
+          },
+        ],
       },
     });
-    expect(plugin.permissions?.fs?.[0]).toBe("read:./local/**");
-    expect(plugin.permissions?.net?.[0]).toBe("fetch:https://api.example.com/**");
+    expect(def.contributions?.graders?.length).toBe(1);
+  });
+});
+
+describe("canonicalJson", () => {
+  test("serialises primitives", () => {
+    expect(canonicalJson(null)).toBe("null");
+    expect(canonicalJson(true)).toBe("true");
+    expect(canonicalJson(false)).toBe("false");
+    expect(canonicalJson(42)).toBe("42");
+    expect(canonicalJson("hi")).toBe('"hi"');
+  });
+
+  test("rejects non-finite numbers", () => {
+    expect(() => canonicalJson(Number.NaN)).toThrow(PluginSdkError);
+    expect(() => canonicalJson(Number.POSITIVE_INFINITY)).toThrow(PluginSdkError);
+  });
+
+  test("sorts object keys deterministically", () => {
+    const a = canonicalJson({ z: 1, a: 2, m: 3 });
+    const b = canonicalJson({ a: 2, m: 3, z: 1 });
+    expect(a).toBe(b);
+    expect(a).toBe('{"a":2,"m":3,"z":1}');
+  });
+
+  test("recurses into nested objects + arrays", () => {
+    const out = canonicalJson({
+      list: [{ b: 2, a: 1 }, "str"],
+      obj: { z: { y: 1 } },
+    });
+    expect(out).toBe('{"list":[{"a":1,"b":2},"str"],"obj":{"z":{"y":1}}}');
+  });
+
+  test("drops undefined keys", () => {
+    const out = canonicalJson({ a: 1, b: undefined, c: 3 });
+    expect(out).toBe('{"a":1,"c":3}');
+  });
+});
+
+describe("manifestPayloadForSigning", () => {
+  test("excludes signature from the canonical payload", () => {
+    const manifest = {
+      name: "my-plugin",
+      version: "1.0.0",
+      signature: {
+        algorithm: "ed25519" as const,
+        publicKeyB64: "pk",
+        sigB64: "sig",
+      },
+    };
+    const payload = manifestPayloadForSigning(manifest);
+    expect(payload).not.toContain("signature");
+    expect(payload).not.toContain("ed25519");
+    expect(payload).toContain("my-plugin");
+  });
+
+  test("matches canonicalJson when no signature is present", () => {
+    const manifest = { name: "my-plugin", version: "1.0.0" };
+    expect(manifestPayloadForSigning(manifest)).toBe(canonicalJson(manifest));
+  });
+
+  test("signing payload is stable across signature mutations", () => {
+    const base = { name: "my-plugin", version: "1.0.0", description: "demo" };
+    const signed1 = {
+      ...base,
+      signature: { algorithm: "ed25519" as const, publicKeyB64: "a", sigB64: "b" },
+    };
+    const signed2 = {
+      ...base,
+      signature: { algorithm: "ed25519" as const, publicKeyB64: "c", sigB64: "d" },
+    };
+    expect(manifestPayloadForSigning(signed1)).toBe(manifestPayloadForSigning(signed2));
   });
 });

package/src/index.ts

@@ -1,29 +1,39 @@
+import { createHash } from "node:crypto";
+import { CrewhausError } from "@crewhaus/errors";
+import type { RegisteredTool, ToolDefinition } from "@crewhaus/tool-catalog";
+
 /**
- * Catalog F5 `plugin-sdk` — Section 26 Studio.
+ * Section 41 — `@crewhaus/plugin-sdk` v2.
+ *
+ * Public typed surface for third-party plugins. A plugin is a single
+ * TS/JS module exporting `definePlugin({ … })`. The §41 `plugin-loader`
+ * loads + activates plugins at runtime; the §42 `plugin-registry`
+ * discovers them; the §40 sigstore-style signature verification runs
+ * before either.
  *
- * 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).
+ * v2 widens the v1 surface (Studio-only — see `crewhaus/utilities/plugin-sdk`)
+ * to cover the five extension points the catalog cares about:
  *
- * 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
+ *   1. **Tools** — anything you would otherwise pass to `buildTool()`.
+ *   2. **Channels** — `ChannelAdapter`-shaped inbound surface (Slack,
+ *      Telegram, … plus future plugins like Mastodon, IRC, etc.).
+ *   3. **Models** — provider adapters that match the canonical
+ *      `ProviderAdapter` contract from `adapter-anthropic`.
+ *   4. **Graders** — evaluators that match the `RegisteredGrader`
+ *      contract from `grader-registry`.
+ *   5. **Target emitters** — compile-time target backends that match
+ *      the `Emitter` contract from `compiler-core`.
  *
- * 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).
+ * The contributions are *declarations*; `plugin-loader` is responsible
+ * for wiring each declaration into the host's registry at runtime
+ * (and for enforcing the `permissions` allow-list).
+ *
+ * The SDK is intentionally **dependency-light**: it only imports
+ * `@crewhaus/errors` + `@crewhaus/tool-catalog` (to expose the
+ * `ToolDefinition` type plugins already know). Other contract types
+ * are re-exported as structural shapes so a plugin author doesn't
+ * have to pull in five workspace packages just to declare a manifest.
  */
-import { CrewhausError } from "@crewhaus/errors";
 
 export class PluginSdkError extends CrewhausError {
   override readonly name = "PluginSdkError";
@@ -32,187 +42,316 @@ export class PluginSdkError extends CrewhausError {
   }
 }
 
-export type StudioPluginPane = {
+// ---------------------------------------------------------------------------
+// Re-exported contract types
+// ---------------------------------------------------------------------------
+
+export type { RegisteredTool, ToolDefinition } from "@crewhaus/tool-catalog";
+
+/**
+ * Structural shape of a channel adapter contribution. Matches the
+ * `ChannelAdapter` interface duplicated across `channel-adapter-slack`
+ * / `-telegram` / `-discord` / `-whatsapp` / `-imessage`. Plugins
+ * implement this shape directly; `plugin-loader` adapts it into the
+ * channel registry slot for the target shape.
+ */
+export interface PluginChannelAdapter {
   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;
-};
+  verify(req: { headers: Headers; body: string }): Promise<boolean>;
+  parseInbound(req: { headers: Headers; body: string }): Promise<unknown>;
+  sendReply(args: {
+    channelId: string;
+    threadKey?: string;
+    text: string;
+    [k: string]: unknown;
+  }): Promise<void>;
+  setTyping?(args: { channelId: string; on: boolean }): Promise<void>;
+}
 
-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;
-};
+/**
+ * Structural shape of a provider adapter. Mirrors the `ProviderAdapter`
+ * exported from `adapter-anthropic` without forcing the SDK to import
+ * that package's transitive deps. The full provider request / stream
+ * event types live in `adapter-anthropic`; plugins implementing this
+ * type should import those for accurate parameter shapes.
+ */
+export interface PluginModelAdapter {
+  readonly id: string;
+  readonly features: {
+    readonly caching?: boolean;
+    readonly tool_use?: boolean;
+    readonly vision?: boolean;
+    readonly thinking?: boolean;
+    readonly web_search?: boolean;
+  };
+  stream(request: unknown): AsyncIterable<unknown>;
+  countTokens?(messages: unknown): Promise<number>;
+}
 
 /**
- * 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.
+ * Structural shape of a grader contribution. Matches `RegisteredGrader`
+ * from `grader-registry`.
+ */
+export interface PluginGrader {
+  readonly id: string;
+  readonly description?: string;
+  grade(sample: { input: unknown; output: unknown; expected?: unknown }): Promise<{
+    pass: boolean;
+    score?: number;
+    notes?: string;
+  }>;
+}
+
+/**
+ * Structural shape of a target emitter contribution. Matches the
+ * `Emitter` contract from `compiler-core` — a function that takes the
+ * IR variant and returns a `Bundle` (file list).
+ */
+export interface PluginTargetEmitter {
+  readonly targetShape: string;
+  emit(ir: unknown): {
+    readonly files: ReadonlyArray<{ readonly path: string; readonly contents: string }>;
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Manifest shape
+// ---------------------------------------------------------------------------
+
+/**
+ * Capability declarations. Fail-closed — an undefined section means the
+ * plugin has zero access to that resource class.
  */
 export type PluginPermissions = {
+  /** Filesystem allow-list (minimatch globs relative to the plugin's sandbox root). */
   readonly fs?: ReadonlyArray<string>;
+  /** URL prefix allow-list for `fetch()` from inside the plugin. */
   readonly net?: ReadonlyArray<string>;
+  /** Names of host-provided tools the plugin's tools may call. */
+  readonly tools?: ReadonlyArray<string>;
+  /** Env-var names the plugin is permitted to read via the host's `secrets-manager`. */
+  readonly secrets?: ReadonlyArray<string>;
 };
 
-export type StudioPluginDefinition = {
+export type PluginSignatureAlgorithm = "ed25519";
+
+/**
+ * Detached signature over the canonical-JSON serialisation of the
+ * manifest with `signature` set to `undefined`. Verified by §42
+ * `plugin-registry` before any source is read.
+ */
+export type PluginSignature = {
+  readonly algorithm: PluginSignatureAlgorithm;
+  readonly publicKeyB64: string;
+  readonly sigB64: string;
+  /** Optional ISO-8601 timestamp; advisory only. */
+  readonly issuedAt?: string;
+};
+
+export type PluginContributions = {
+  readonly tools?: ReadonlyArray<RegisteredTool | ToolDefinition>;
+  readonly channels?: ReadonlyArray<PluginChannelAdapter>;
+  readonly models?: ReadonlyArray<PluginModelAdapter>;
+  readonly graders?: ReadonlyArray<PluginGrader>;
+  readonly targetEmitters?: ReadonlyArray<PluginTargetEmitter>;
+};
+
+export type PluginManifest = {
+  /** Globally-unique kebab-case plugin id. */
   readonly name: string;
-  /** Semver-shaped version string. Studio renders this in the plugins panel. */
+  /** Semver-shaped version string (validated by `validatePluginManifest`). */
   readonly version: string;
-  readonly hooks?: StudioPluginHooks;
-  readonly panes?: ReadonlyArray<StudioPluginPane>;
-  /**
-   * Optional one-line description shown in the plugins panel.
-   */
   readonly description?: string;
+  readonly author?: string;
+  readonly homepage?: string;
+  readonly license?: string;
+  /** Minimum crewhaus runtime version this plugin requires (semver range). */
+  readonly engines?: { readonly crewhaus?: string };
+  readonly permissions?: PluginPermissions;
+  readonly contributions?: PluginContributions;
   /**
-   * Section 31 — declared permissions allow-list. Optional; absent
-   * means "no fs / no net access" (fail-closed).
+   * Lowercase hex SHA-256 of the plugin's entrypoint (`index.js`). It is part
+   * of the manifest, so `manifestPayloadForSigning` includes it and the
+   * signature therefore commits to the CODE, not just the metadata. The loader
+   * refuses to `import()` an entrypoint whose hash does not match. Optional for
+   * back-compat; signed plugins SHOULD set it (compute via `entrypointDigest`).
    */
-  readonly permissions?: PluginPermissions;
+  readonly entrypointDigest?: string;
+  readonly signature?: PluginSignature;
 };
 
-/**
- * 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");
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+
+const NAME_PATTERN = /^[a-z][a-z0-9-]{1,62}[a-z0-9]$/;
+const SEMVER_PATTERN = /^\d+\.\d+\.\d+(?:-[\w.+-]+)?(?:\+[\w.-]+)?$/;
+
+function assertString(value: unknown, field: string): asserts value is string {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new PluginSdkError(`plugin manifest: \`${field}\` must be a non-empty string`);
   }
-  if (typeof def.version !== "string" || def.version.length === 0) {
-    throw new PluginSdkError("definePlugin: `version` is required");
+}
+
+function assertOptionalString(value: unknown, field: string): asserts value is string | undefined {
+  if (value !== undefined && (typeof value !== "string" || value.length === 0)) {
+    throw new PluginSdkError(
+      `plugin manifest: \`${field}\` must be a non-empty string when present`,
+    );
+  }
+}
+
+function assertOptionalStringArray(
+  value: unknown,
+  field: string,
+): asserts value is ReadonlyArray<string> | undefined {
+  if (value === undefined) return;
+  if (!Array.isArray(value)) {
+    throw new PluginSdkError(`plugin manifest: \`${field}\` must be an array of strings`);
   }
-  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}"`);
+  for (const item of value) {
+    if (typeof item !== "string" || item.length === 0) {
+      throw new PluginSdkError(`plugin manifest: \`${field}\` entries must be non-empty strings`);
     }
-    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.
+ * Throw `PluginSdkError` if `m` is not a valid `PluginManifest`. Returns
+ * the input typed as `PluginManifest` on success (used as a type guard).
  */
-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}`,
-        );
-      }
+export function validatePluginManifest(m: unknown): PluginManifest {
+  if (m === null || typeof m !== "object") {
+    throw new PluginSdkError("plugin manifest must be an object");
+  }
+  const manifest = m as Record<string, unknown>;
+  assertString(manifest["name"], "name");
+  if (!NAME_PATTERN.test(manifest["name"])) {
+    throw new PluginSdkError(
+      `plugin manifest: \`name\` must be 3-64 chars, lowercase a-z / 0-9 / "-", start with a letter, no trailing hyphen (got "${manifest["name"]}")`,
+    );
+  }
+  assertString(manifest["version"], "version");
+  if (!SEMVER_PATTERN.test(manifest["version"])) {
+    throw new PluginSdkError(
+      `plugin manifest: \`version\` must be semver-shaped (got "${manifest["version"]}")`,
+    );
+  }
+  assertOptionalString(manifest["description"], "description");
+  assertOptionalString(manifest["author"], "author");
+  assertOptionalString(manifest["homepage"], "homepage");
+  assertOptionalString(manifest["license"], "license");
+
+  if (manifest["entrypointDigest"] !== undefined) {
+    assertString(manifest["entrypointDigest"], "entrypointDigest");
+    if (!/^[a-f0-9]{64}$/.test(manifest["entrypointDigest"] as string)) {
+      throw new PluginSdkError(
+        "plugin manifest: `entrypointDigest` must be a lowercase hex SHA-256 (64 chars)",
+      );
+    }
+  }
+
+  if (manifest["engines"] !== undefined) {
+    const engines = manifest["engines"];
+    if (engines === null || typeof engines !== "object") {
+      throw new PluginSdkError("plugin manifest: `engines` must be an object");
+    }
+    assertOptionalString((engines as Record<string, unknown>)["crewhaus"], "engines.crewhaus");
+  }
+
+  if (manifest["permissions"] !== undefined) {
+    const perms = manifest["permissions"];
+    if (perms === null || typeof perms !== "object") {
+      throw new PluginSdkError("plugin manifest: `permissions` must be an object");
+    }
+    const p = perms as Record<string, unknown>;
+    assertOptionalStringArray(p["fs"], "permissions.fs");
+    assertOptionalStringArray(p["net"], "permissions.net");
+    assertOptionalStringArray(p["tools"], "permissions.tools");
+    assertOptionalStringArray(p["secrets"], "permissions.secrets");
+  }
+
+  if (manifest["signature"] !== undefined) {
+    const sig = manifest["signature"];
+    if (sig === null || typeof sig !== "object") {
+      throw new PluginSdkError("plugin manifest: `signature` must be an object");
+    }
+    const s = sig as Record<string, unknown>;
+    if (s["algorithm"] !== "ed25519") {
+      throw new PluginSdkError('plugin manifest: `signature.algorithm` must be "ed25519"');
     }
+    assertString(s["publicKeyB64"], "signature.publicKeyB64");
+    assertString(s["sigB64"], "signature.sigB64");
+    assertOptionalString(s["issuedAt"], "signature.issuedAt");
   }
+
+  return manifest as unknown as PluginManifest;
 }
 
 /**
- * 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.
+ * Type-only helper plugins use:
+ *   export default definePlugin({ name, version, contributions, … });
  *
- * Empty / undefined permissions = fail-closed (deny all).
+ * Runs `validatePluginManifest` so misconfiguration fails at load time
+ * (before the plugin's tools are exposed to a host).
  */
-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 definePlugin<T extends PluginManifest>(def: T): T {
+  validatePluginManifest(def);
+  return def;
 }
 
-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));
+// ---------------------------------------------------------------------------
+// Canonical JSON (for signature payload)
+// ---------------------------------------------------------------------------
+
+/**
+ * Deterministic JSON serialisation: sorted keys, no whitespace, `undefined`
+ * keys omitted. This is the byte string that the `signature` is computed
+ * over (with `signature` itself set to `undefined`).
+ *
+ * Mirrors the §40 template-marketplace-client canonical-JSON convention
+ * so plugin signatures verify with the same crypto primitive.
+ */
+export function canonicalJson(value: unknown): string {
+  if (value === null) return "null";
+  if (typeof value === "boolean") return value ? "true" : "false";
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw new PluginSdkError("canonical JSON: non-finite numbers are not representable");
+    }
+    return JSON.stringify(value);
+  }
+  if (typeof value === "string") return JSON.stringify(value);
+  if (Array.isArray(value)) {
+    return `[${value.map((v) => canonicalJson(v)).join(",")}]`;
+  }
+  if (typeof value === "object") {
+    const obj = value as Record<string, unknown>;
+    const keys = Object.keys(obj)
+      .filter((k) => obj[k] !== undefined)
+      .sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalJson(obj[k])}`).join(",")}}`;
+  }
+  throw new PluginSdkError(`canonical JSON: unsupported type ${typeof value}`);
 }
 
 /**
- * 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.
+ * Returns the byte string the plugin's signature should verify against
+ * — the manifest's canonical JSON with `signature` cleared.
  */
-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);
+export function manifestPayloadForSigning(manifest: PluginManifest): string {
+  // Shallow clone, drop signature, then canonical-encode. `entrypointDigest`
+  // is NOT dropped, so the signature commits to the plugin code via its hash.
+  const { signature: _signature, ...rest } = manifest;
+  return canonicalJson(rest);
 }
 
 /**
- * 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.
+ * Compute the `entrypointDigest` for plugin code — the lowercase hex SHA-256 of
+ * the entrypoint file's bytes. Plugin signing tools set the result on the
+ * manifest's `entrypointDigest` before signing; the loader recomputes it from
+ * the on-disk `index.js` and refuses to import on mismatch.
  */
-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:"`);
-    }
-  }
+export function entrypointDigest(code: string | Uint8Array): string {
+  return createHash("sha256").update(code).digest("hex");
 }

package/README.md

@@ -1,98 +0,0 @@
-# `@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/src/scripts/start.ts

@@ -1,58 +0,0 @@
-/**
- * `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`);
-}