@stigmer/server 3.15.3-dev.20260914121148 → 3.16.0

package/src/domain/plugin/__tests__/sanitize.test.ts

@@ -0,0 +1,174 @@
+/**
+ * Pins the sanitiser, the one place plugin-provided metadata is judged
+ * before it rides the in-process lane: a `stigmer.ai/*` label in an
+ * overlay is refused INVALID_ARGUMENT naming the document and the keys
+ * under a denying authorizer and passes under an allowing one (the
+ * open-source posture), the operator check is consulted lazily and only
+ * for the platform capability, a preset id and a name that describes
+ * another resource are refused as INVALID_ARGUMENT, and clean documents
+ * pass without touching the authorizer.
+ */
+import { describe, expect, it } from "vitest";
+import { Code, ConnectError } from "@connectrpc/connect";
+import { create } from "@bufbuild/protobuf";
+
+import { AgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import { McpServerSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { IamPermission } from "@stigmer/protos/ai/stigmer/iam/v1/enum_pb";
+
+import type { Authorizer, AuthzCheck } from "../../../extensions/authorizer.js";
+import type { CallerIdentity } from "../../../extensions/identity.js";
+import type { ParsedOverlays } from "../overlay/documents.js";
+import { sanitizeOverlays } from "../overlay/sanitize.js";
+
+const USER: CallerIdentity = {
+  identityId: "ida_alice",
+  callerClass: "user",
+  issuer: "stigmer",
+  rawToken: "tok",
+};
+
+function denying(observed?: AuthzCheck[]): Authorizer {
+  return {
+    authorize: (_caller, check) => {
+      observed?.push(check);
+      return Promise.resolve({ kind: "deny", reason: "" });
+    },
+  };
+}
+function allowing(observed?: AuthzCheck[]): Authorizer {
+  return {
+    authorize: (_caller, check) => {
+      observed?.push(check);
+      return Promise.resolve({ kind: "allow" });
+    },
+  };
+}
+
+function overlays(parts: Partial<ParsedOverlays>): ParsedOverlays {
+  return { workflows: [], mcpServers: [], ...parts };
+}
+
+function agentOverlay(metadata: {
+  name?: string;
+  slug?: string;
+  id?: string;
+  labels?: Record<string, string>;
+}) {
+  return {
+    path: "ai.stigmer/agent.yaml",
+    resource: create(AgentSchema, { metadata: { org: "acme", ...metadata } }),
+  };
+}
+
+async function failure(promise: Promise<void>): Promise<ConnectError> {
+  try {
+    await promise;
+  } catch (error) {
+    expect(error).toBeInstanceOf(ConnectError);
+    return error as ConnectError;
+  }
+  throw new Error("expected a refusal");
+}
+
+describe("sanitizeOverlays", () => {
+  it("refuses a reserved label under a denying authorizer, naming the document and the keys", async () => {
+    const error = await failure(
+      sanitizeOverlays(
+        overlays({
+          agent: agentOverlay({
+            labels: { "stigmer.ai/default-agent": "true", team: "x" },
+          }),
+        }),
+        { pluginName: "thermos" },
+        denying(),
+        USER,
+      ),
+    );
+    expect(error.code).toBe(Code.InvalidArgument);
+    expect(error.rawMessage).toContain(
+      "ai.stigmer/agent.yaml: stigmer.ai/default-agent",
+    );
+    expect(error.rawMessage).toContain(
+      "Remove them from the plugin's ai.stigmer/ documents.",
+    );
+  });
+
+  it("passes a reserved label under an allowing authorizer, consulting exactly the platform capability", async () => {
+    const observed: AuthzCheck[] = [];
+    await sanitizeOverlays(
+      overlays({
+        agent: agentOverlay({ labels: { "stigmer.ai/default-agent": "true" } }),
+      }),
+      { pluginName: "thermos" },
+      allowing(observed),
+      USER,
+    );
+    expect(observed).toEqual([
+      {
+        permission: IamPermission.can_write_reserved_labels,
+        resourceKind: ApiResourceKind.platform,
+        resourceId: "stigmer",
+      },
+    ]);
+  });
+
+  it("never consults the authorizer for documents without reserved keys", async () => {
+    const observed: AuthzCheck[] = [];
+    await sanitizeOverlays(
+      overlays({
+        agent: agentOverlay({ name: "thermos", labels: { team: "x" } }),
+        mcpServers: [
+          {
+            path: "ai.stigmer/mcp-servers/github.yaml",
+            server: "github",
+            resource: create(McpServerSchema, { metadata: { name: "github" } }),
+          },
+        ],
+      }),
+      { pluginName: "thermos" },
+      denying(observed),
+      USER,
+    );
+    expect(observed).toEqual([]);
+  });
+
+  it("refuses a preset metadata.id", async () => {
+    const error = await failure(
+      sanitizeOverlays(
+        overlays({ agent: agentOverlay({ id: "agt_forged" }) }),
+        { pluginName: "thermos" },
+        denying(),
+        USER,
+      ),
+    );
+    expect(error.code).toBe(Code.InvalidArgument);
+    expect(error.rawMessage).toBe(
+      "overlay document 'ai.stigmer/agent.yaml' sets metadata.id; a plugin's resources take their ids from the server",
+    );
+  });
+
+  it("refuses an overlay whose name describes another resource", async () => {
+    const error = await failure(
+      sanitizeOverlays(
+        overlays({
+          mcpServers: [
+            {
+              path: "ai.stigmer/mcp-servers/github.yaml",
+              server: "github",
+              resource: create(McpServerSchema, {
+                metadata: { name: "gitlab" },
+              }),
+            },
+          ],
+        }),
+        { pluginName: "thermos" },
+        denying(),
+        USER,
+      ),
+    );
+    expect(error.code).toBe(Code.InvalidArgument);
+    expect(error.rawMessage).toContain("names 'gitlab' but describes 'github'");
+  });
+});

package/src/domain/plugin/archive.ts

@@ -0,0 +1,89 @@
+/**
+ * The plugin archive gate: the pushed ZIP becomes the `PluginFiles` reader
+ * `@stigmer/plugin-package` is pure over, and the bytes' SHA-256 becomes
+ * the plugin's version identity. Composes the shared archive plumbing
+ * (src/archive): open, hash, prefilter and the structural walk exactly as
+ * the skill gate, then a lazy reader whose `read` inflates one entry under
+ * the central directory's declared size as the real cap and verifies its
+ * CRC — the library refuses an over-cap DECLARATION before asking, and this
+ * reader refuses an over-cap INFLATION, so a bomb is caught on both sides.
+ *
+ * Nothing here knows what a plugin IS: manifests, skills and overlays are
+ * the library's to find. This module knows what an ARCHIVE is and how to
+ * hand its files to the library without inflating anything nobody asked
+ * for.
+ *
+ * Error text is wire-visible: the shared gate's sentences pass through
+ * verbatim (the same limits skills quote), and a failed read names the
+ * entry. The push step wraps them into its InvalidArgument arm.
+ *
+ * Proven by __tests__/archive.test.ts.
+ */
+import type { PluginFileEntry, PluginFiles } from "@stigmer/plugin-package";
+import { comparePaths, isContainedPath } from "@stigmer/plugin-package";
+
+import { InflateError, inflateEntry } from "../../archive/inflate.js";
+import { MAX_ZIP_SIZE, PLATFORM_ARCHIVE_LIMITS } from "../../archive/limits.js";
+import { openArchive, validateArchiveStructure } from "../../archive/open.js";
+import type { PrefilteredEntry } from "../../archive/prefilter.js";
+
+/** A gated archive: its identity and the files the library may read. */
+export interface OpenedPluginArchive {
+  /** SHA-256 hex of the archive bytes — the plugin's version identity. */
+  readonly digest: string;
+  readonly files: PluginFiles;
+}
+
+/**
+ * Gates the archive and builds the lazy reader. Directory entries and
+ * entries whose sanitised name the library would refuse as uncontained are
+ * dropped here rather than surfaced: the prefilter already made every name
+ * unrooted and `..`-free, so what remains is the rare empty-segment name,
+ * which no plugin author writes and no manifest can declare.
+ */
+export function openPluginArchive(bytes: Uint8Array): OpenedPluginArchive {
+  const { hash, entries } = openArchive(bytes, MAX_ZIP_SIZE);
+  validateArchiveStructure(entries, PLATFORM_ARCHIVE_LIMITS);
+
+  const byPath = new Map<string, PrefilteredEntry>();
+  for (const prefiltered of entries) {
+    const { name } = prefiltered;
+    if (name.endsWith("/") || !isContainedPath(name)) {
+      continue;
+    }
+    // Two entries sanitising to one name (`a/../b.md` beside `b.md`): the
+    // first wins, as the skill gate's "first root-named entry" rule reads.
+    if (!byPath.has(name)) {
+      byPath.set(name, prefiltered);
+    }
+  }
+
+  const fileEntries: PluginFileEntry[] = [...byPath.values()]
+    .map(({ name, entry }) => ({ path: name, size: entry.uncompressedSize }))
+    .sort((a, b) => comparePaths(a.path, b.path));
+
+  const files: PluginFiles = {
+    entries: fileEntries,
+    read(path: string): Uint8Array {
+      const prefiltered = byPath.get(path);
+      if (prefiltered === undefined) {
+        throw new Error(`plugin file '${path}' is not listed`);
+      }
+      try {
+        return inflateEntry(
+          prefiltered.entry,
+          prefiltered.entry.uncompressedSize,
+        );
+      } catch (error) {
+        if (error instanceof InflateError) {
+          throw new Error(
+            `failed to read '${path}' from the plugin archive: ${error.detail}`,
+          );
+        }
+        throw error;
+      }
+    },
+  };
+
+  return { digest: hash, files };
+}

package/src/domain/plugin/constants.ts

@@ -0,0 +1,53 @@
+/**
+ * Plugin domain constants — every wire-visible string and pinned value in
+ * one place (guidelines: errors are API surface; the CLI, console and SDK
+ * show these verbatim). The archive budgets are the platform's
+ * (src/archive/limits.ts); what is a plugin's is here.
+ */
+
+/** Storage key prefix for plugin archives: "plugins/<digest>.zip". */
+export const PLUGIN_ARTIFACT_KEY_PREFIX = "plugins/";
+
+/**
+ * A manifest version becomes the plugin's audit tag only when it fits the
+ * tag pattern every versioned kind shares (`spec.tag` on skills). Semantic
+ * Versioning build metadata (`1.0.0+build.1`) does not fit; such a version
+ * installs untagged with a warning rather than refusing the plugin.
+ */
+export const VERSION_TAG_PATTERN = /^[a-zA-Z0-9._-]+$/;
+
+/**
+ * The runner's built-in sub-agents. A plugin sub-agent bearing one of these
+ * names shadows a built-in at run time; the runner only warns, so the
+ * install warns too rather than refusing (an M1 finding kept as data here).
+ */
+export const BUILT_IN_SUB_AGENT_NAMES: ReadonlySet<string> = new Set([
+  "explore",
+  "shell",
+  "general-purpose",
+]);
+
+/**
+ * The materialisation order and the kinds a plugin may own, in the order
+ * references resolve: an agent names skills and servers, a workflow may
+ * name the agent. Cascade deletes in reverse.
+ */
+export const MATERIALIZATION_ORDER = [
+  "skill",
+  "mcp_server",
+  "agent",
+  "workflow",
+] as const;
+export type MaterializedKindName = (typeof MATERIALIZATION_ORDER)[number];
+
+/** FailedPrecondition copy when the upload lane was not configured. */
+export const TRANSFER_LANE_NOT_CONFIGURED =
+  "plugin artifact transfer lane is not configured on this server";
+
+/** Warning kinds the SERVER adds to the library's; the wire carries them as strings. */
+export const SERVER_WARNING_KINDS = {
+  componentIgnored: "component-ignored",
+  modelHintUnresolved: "model-hint-unresolved",
+  subAgentNameBuiltin: "sub-agent-name-builtin",
+  versionNotTaggable: "version-not-taggable",
+} as const;