@vellumai/assistant 0.6.3 → 0.6.5

package/src/permissions/skill-risk-classifier.test.ts

@@ -0,0 +1,311 @@
+import { describe, expect, mock, test } from "bun:test";
+
+// ── Mocks ────────────────────────────────────────────────────────────────────
+
+// Mock skill resolution so we can control version hashes and catalog lookups.
+let mockResolvedSkill: {
+  id: string;
+  directoryPath: string;
+} | null = null;
+let mockVersionHash: string | undefined;
+let mockTransitiveHash: string | undefined;
+let mockInlineExpansions: string[] = [];
+let mockInlineEnabled = false;
+
+mock.module("../config/skills.js", () => ({
+  resolveSkillSelector: (_selector: string) => ({
+    skill: mockResolvedSkill,
+  }),
+  loadSkillCatalog: () =>
+    mockResolvedSkill
+      ? [
+          {
+            id: mockResolvedSkill.id,
+            directoryPath: mockResolvedSkill.directoryPath,
+            inlineCommandExpansions:
+              mockInlineExpansions.length > 0
+                ? mockInlineExpansions
+                : undefined,
+          },
+        ]
+      : [],
+}));
+
+mock.module("../skills/version-hash.js", () => ({
+  computeSkillVersionHash: () => {
+    if (mockVersionHash === undefined) throw new Error("no hash");
+    return mockVersionHash;
+  },
+}));
+
+mock.module("../skills/transitive-version-hash.js", () => ({
+  computeTransitiveSkillVersionHash: () => {
+    if (mockTransitiveHash === undefined) throw new Error("no hash");
+    return mockTransitiveHash;
+  },
+}));
+
+mock.module("../skills/include-graph.js", () => ({
+  indexCatalogById: () => new Map(),
+}));
+
+mock.module("../config/loader.js", () => ({
+  getConfig: () => ({}),
+}));
+
+mock.module("../config/assistant-feature-flags.js", () => ({
+  isAssistantFeatureFlagEnabled: () => mockInlineEnabled,
+}));
+
+import {
+  type SkillClassifierInput,
+  SkillLoadRiskClassifier,
+  skillLoadRiskClassifier,
+} from "./skill-risk-classifier.js";
+
+// ── Test helpers ─────────────────────────────────────────────────────────────
+
+function resetMocks(): void {
+  mockResolvedSkill = null;
+  mockVersionHash = undefined;
+  mockTransitiveHash = undefined;
+  mockInlineExpansions = [];
+  mockInlineEnabled = false;
+}
+
+// ── SkillLoadRiskClassifier ──────────────────────────────────────────────────
+
+describe("SkillLoadRiskClassifier", () => {
+  test("skill_load is always Low risk", async () => {
+    resetMocks();
+    const classifier = new SkillLoadRiskClassifier();
+    const result = await classifier.classify({ toolName: "skill_load" });
+    expect(result.riskLevel).toBe("low");
+    expect(result.reason).toBe("Skill load (default)");
+    expect(result.scopeOptions).toEqual([]);
+    expect(result.matchType).toBe("registry");
+  });
+
+  test("scaffold_managed_skill is always High risk", async () => {
+    resetMocks();
+    const classifier = new SkillLoadRiskClassifier();
+    const result = await classifier.classify({
+      toolName: "scaffold_managed_skill",
+    });
+    expect(result.riskLevel).toBe("high");
+    expect(result.reason).toBe(
+      "Skill scaffold — writes persistent skill source code",
+    );
+    expect(result.scopeOptions).toEqual([]);
+    expect(result.matchType).toBe("registry");
+  });
+
+  test("delete_managed_skill is always High risk", async () => {
+    resetMocks();
+    const classifier = new SkillLoadRiskClassifier();
+    const result = await classifier.classify({
+      toolName: "delete_managed_skill",
+    });
+    expect(result.riskLevel).toBe("high");
+    expect(result.reason).toBe(
+      "Skill delete — removes persistent skill source code",
+    );
+    expect(result.scopeOptions).toEqual([]);
+    expect(result.matchType).toBe("registry");
+  });
+
+  test("skill_load with skillSelector is still Low risk", async () => {
+    resetMocks();
+    const classifier = new SkillLoadRiskClassifier();
+    const result = await classifier.classify({
+      toolName: "skill_load",
+      skillSelector: "my-custom-skill",
+    });
+    expect(result.riskLevel).toBe("low");
+    expect(result.reason).toBe("Skill load (default)");
+  });
+
+  test("scaffold_managed_skill with skillSelector is still High risk", async () => {
+    resetMocks();
+    const classifier = new SkillLoadRiskClassifier();
+    const result = await classifier.classify({
+      toolName: "scaffold_managed_skill",
+      skillSelector: "new-skill",
+    });
+    expect(result.riskLevel).toBe("high");
+  });
+
+  test("delete_managed_skill with skillSelector is still High risk", async () => {
+    resetMocks();
+    const classifier = new SkillLoadRiskClassifier();
+    const result = await classifier.classify({
+      toolName: "delete_managed_skill",
+      skillSelector: "old-skill",
+    });
+    expect(result.riskLevel).toBe("high");
+  });
+});
+
+// ── Allowlist options ────────────────────────────────────────────────────────
+
+describe("allowlistOptions", () => {
+  test("skill_load without selector produces wildcard option", async () => {
+    resetMocks();
+    const classifier = new SkillLoadRiskClassifier();
+    const result = await classifier.classify({ toolName: "skill_load" });
+    expect(result.allowlistOptions).toEqual([
+      {
+        label: "skill_load:*",
+        description: "All skill loads",
+        pattern: "skill_load:*",
+      },
+    ]);
+  });
+
+  test("skill_load with unresolvable selector produces selector-based option", async () => {
+    resetMocks();
+    // mockResolvedSkill is null — skill not found
+    const classifier = new SkillLoadRiskClassifier();
+    const result = await classifier.classify({
+      toolName: "skill_load",
+      skillSelector: "unknown-skill",
+    });
+    expect(result.allowlistOptions).toEqual([
+      {
+        label: "unknown-skill",
+        description: "This skill",
+        pattern: "skill_load:unknown-skill",
+      },
+    ]);
+  });
+
+  test("skill_load with resolved skill + version hash produces version-pinned option", async () => {
+    resetMocks();
+    mockResolvedSkill = { id: "my-skill", directoryPath: "/skills/my-skill" };
+    mockVersionHash = "abc123";
+
+    const classifier = new SkillLoadRiskClassifier();
+    const result = await classifier.classify({
+      toolName: "skill_load",
+      skillSelector: "my-skill",
+    });
+    expect(result.allowlistOptions).toEqual([
+      {
+        label: "my-skill@abc123",
+        description: "This exact version",
+        pattern: "skill_load:my-skill@abc123",
+      },
+    ]);
+  });
+
+  test("skill_load with dynamic skill produces version-pinned + any-version options", async () => {
+    resetMocks();
+    mockResolvedSkill = {
+      id: "dynamic-skill",
+      directoryPath: "/skills/dynamic-skill",
+    };
+    mockVersionHash = "def456";
+    mockTransitiveHash = "trans789";
+    mockInlineExpansions = ["some-command"];
+    mockInlineEnabled = true;
+
+    const classifier = new SkillLoadRiskClassifier();
+    const result = await classifier.classify({
+      toolName: "skill_load",
+      skillSelector: "dynamic-skill",
+    });
+    expect(result.allowlistOptions).toEqual([
+      {
+        label: "dynamic-skill@trans789",
+        description: "This exact version (pinned)",
+        pattern: "skill_load_dynamic:dynamic-skill@trans789",
+      },
+      {
+        label: "dynamic-skill",
+        description: "This skill (any version)",
+        pattern: "skill_load_dynamic:dynamic-skill",
+      },
+    ]);
+  });
+
+  test("scaffold_managed_skill produces skill-specific + wildcard options", async () => {
+    resetMocks();
+    const classifier = new SkillLoadRiskClassifier();
+    const result = await classifier.classify({
+      toolName: "scaffold_managed_skill",
+      skillSelector: "new-skill",
+    });
+    expect(result.allowlistOptions).toEqual([
+      {
+        label: "new-skill",
+        description: "This skill only",
+        pattern: "scaffold_managed_skill:new-skill",
+      },
+      {
+        label: "scaffold_managed_skill:*",
+        description: "All managed skill scaffolds",
+        pattern: "scaffold_managed_skill:*",
+      },
+    ]);
+  });
+
+  test("delete_managed_skill produces skill-specific + wildcard options", async () => {
+    resetMocks();
+    const classifier = new SkillLoadRiskClassifier();
+    const result = await classifier.classify({
+      toolName: "delete_managed_skill",
+      skillSelector: "old-skill",
+    });
+    expect(result.allowlistOptions).toEqual([
+      {
+        label: "old-skill",
+        description: "This skill only",
+        pattern: "delete_managed_skill:old-skill",
+      },
+      {
+        label: "delete_managed_skill:*",
+        description: "All managed skill deletes",
+        pattern: "delete_managed_skill:*",
+      },
+    ]);
+  });
+
+  test("scaffold_managed_skill without selector produces only wildcard", async () => {
+    resetMocks();
+    const classifier = new SkillLoadRiskClassifier();
+    const result = await classifier.classify({
+      toolName: "scaffold_managed_skill",
+    });
+    expect(result.allowlistOptions).toEqual([
+      {
+        label: "scaffold_managed_skill:*",
+        description: "All managed skill scaffolds",
+        pattern: "scaffold_managed_skill:*",
+      },
+    ]);
+  });
+});
+
+// ── Singleton export ─────────────────────────────────────────────────────────
+
+describe("singleton", () => {
+  test("skillLoadRiskClassifier is an instance of SkillLoadRiskClassifier", () => {
+    expect(skillLoadRiskClassifier).toBeInstanceOf(SkillLoadRiskClassifier);
+  });
+
+  test("singleton produces same results as fresh instance", async () => {
+    resetMocks();
+    const inputs: SkillClassifierInput[] = [
+      { toolName: "skill_load" },
+      { toolName: "scaffold_managed_skill" },
+      { toolName: "delete_managed_skill" },
+    ];
+
+    const fresh = new SkillLoadRiskClassifier();
+    for (const input of inputs) {
+      const singletonResult = await skillLoadRiskClassifier.classify(input);
+      const freshResult = await fresh.classify(input);
+      expect(singletonResult).toEqual(freshResult);
+    }
+  });
+});

package/src/permissions/skill-risk-classifier.ts

@@ -0,0 +1,214 @@
+/**
+ * Skill risk classifier — classifies skill tool invocations by risk level.
+ *
+ * Implements RiskClassifier<SkillClassifierInput> with constant risk levels
+ * for each skill tool type:
+ * - skill_load: Low (read-only skill loading)
+ * - scaffold_managed_skill: High (writes persistent skill source code)
+ * - delete_managed_skill: High (removes persistent skill source code)
+ */
+
+import { isAssistantFeatureFlagEnabled } from "../config/assistant-feature-flags.js";
+import { getConfig } from "../config/loader.js";
+import { loadSkillCatalog, resolveSkillSelector } from "../config/skills.js";
+import { indexCatalogById } from "../skills/include-graph.js";
+import { computeTransitiveSkillVersionHash } from "../skills/transitive-version-hash.js";
+import { computeSkillVersionHash } from "../skills/version-hash.js";
+import type { RiskAssessment, RiskClassifier } from "./risk-types.js";
+import type { AllowlistOption } from "./types.js";
+
+// ── Input type ───────────────────────────────────────────────────────────────
+
+/** Input to the skill risk classifier. */
+export interface SkillClassifierInput {
+  /** Which skill tool is being invoked. */
+  toolName: "skill_load" | "scaffold_managed_skill" | "delete_managed_skill";
+  /** Optional skill selector (e.g. skill name or path). */
+  skillSelector?: string;
+}
+
+// ── Allowlist option helpers ─────────────────────────────────────────────────
+
+/**
+ * Resolve a skill selector to its id and version hash. The version hash
+ * is always computed from disk so that untrusted input cannot spoof a
+ * pre-approved hash.
+ */
+function resolveSkillIdAndHash(
+  selector: string,
+): { id: string; versionHash?: string } | null {
+  const resolved = resolveSkillSelector(selector);
+  if (!resolved.skill) return null;
+
+  try {
+    const hash = computeSkillVersionHash(resolved.skill.directoryPath);
+    return { id: resolved.skill.id, versionHash: hash };
+  } catch {
+    return { id: resolved.skill.id };
+  }
+}
+
+/**
+ * Check whether a skill (by id) has parsed inline command expansions.
+ */
+function hasInlineExpansions(skillId: string): boolean {
+  const catalog = loadSkillCatalog();
+  const skill = catalog.find((s) => s.id === skillId);
+  return (
+    skill?.inlineCommandExpansions != null &&
+    skill.inlineCommandExpansions.length > 0
+  );
+}
+
+/**
+ * Compute the transitive version hash for a skill, returning `undefined`
+ * when computation fails (missing includes, cycle, etc.).
+ */
+function computeTransitiveHashSafe(skillId: string): string | undefined {
+  try {
+    const catalog = loadSkillCatalog();
+    const index = indexCatalogById(catalog);
+    return computeTransitiveSkillVersionHash(skillId, index);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Build allowlist options for a skill_load invocation, mirroring the logic
+ * in checker.ts `skillLoadAllowlistStrategy()`.
+ */
+function buildSkillLoadAllowlistOptions(
+  rawSelector?: string,
+): AllowlistOption[] {
+  if (!rawSelector) {
+    return [
+      {
+        label: "skill_load:*",
+        description: "All skill loads",
+        pattern: "skill_load:*",
+      },
+    ];
+  }
+
+  const resolved = resolveSkillIdAndHash(rawSelector);
+
+  // Check whether this is a dynamic (inline-command) skill load
+  const config = getConfig();
+  const inlineEnabled = isAssistantFeatureFlagEnabled(
+    "inline-skill-commands",
+    config,
+  );
+
+  if (resolved && inlineEnabled && hasInlineExpansions(resolved.id)) {
+    const transitiveHash = computeTransitiveHashSafe(resolved.id);
+    const options: AllowlistOption[] = [];
+    if (transitiveHash) {
+      options.push({
+        label: `${resolved.id}@${transitiveHash}`,
+        description: "This exact version (pinned)",
+        pattern: `skill_load_dynamic:${resolved.id}@${transitiveHash}`,
+      });
+    }
+    options.push({
+      label: resolved.id,
+      description: "This skill (any version)",
+      pattern: `skill_load_dynamic:${resolved.id}`,
+    });
+    return options;
+  }
+
+  if (resolved && resolved.versionHash) {
+    return [
+      {
+        label: `${resolved.id}@${resolved.versionHash}`,
+        description: "This exact version",
+        pattern: `skill_load:${resolved.id}@${resolved.versionHash}`,
+      },
+    ];
+  }
+  return [
+    {
+      label: rawSelector,
+      description: "This skill",
+      pattern: `skill_load:${rawSelector}`,
+    },
+  ];
+}
+
+/**
+ * Build allowlist options for scaffold/delete managed skill tools,
+ * mirroring the logic in checker.ts `managedSkillAllowlistStrategy()`.
+ */
+function buildManagedSkillAllowlistOptions(
+  toolName: string,
+  skillId?: string,
+): AllowlistOption[] {
+  const toolLabel =
+    toolName === "scaffold_managed_skill" ? "scaffold" : "delete";
+  const options: AllowlistOption[] = [];
+  if (skillId) {
+    options.push({
+      label: skillId,
+      description: "This skill only",
+      pattern: `${toolName}:${skillId}`,
+    });
+  }
+  options.push({
+    label: `${toolName}:*`,
+    description: `All managed skill ${toolLabel}s`,
+    pattern: `${toolName}:*`,
+  });
+  return options;
+}
+
+// ── Classifier ───────────────────────────────────────────────────────────────
+
+/**
+ * Skill risk classifier implementation.
+ *
+ * Classifies skill tool invocations with constant risk levels per tool type.
+ * checker.ts delegates to the singleton `skillLoadRiskClassifier` instance
+ * for all skill tool risk classification.
+ */
+export class SkillLoadRiskClassifier implements RiskClassifier<SkillClassifierInput> {
+  async classify(input: SkillClassifierInput): Promise<RiskAssessment> {
+    const { toolName, skillSelector } = input;
+
+    switch (toolName) {
+      case "skill_load":
+        return {
+          riskLevel: "low",
+          reason: "Skill load (default)",
+          scopeOptions: [],
+          matchType: "registry",
+          allowlistOptions: buildSkillLoadAllowlistOptions(skillSelector),
+        };
+      case "scaffold_managed_skill":
+        return {
+          riskLevel: "high",
+          reason: "Skill scaffold — writes persistent skill source code",
+          scopeOptions: [],
+          matchType: "registry",
+          allowlistOptions: buildManagedSkillAllowlistOptions(
+            toolName,
+            skillSelector,
+          ),
+        };
+      case "delete_managed_skill":
+        return {
+          riskLevel: "high",
+          reason: "Skill delete — removes persistent skill source code",
+          scopeOptions: [],
+          matchType: "registry",
+          allowlistOptions: buildManagedSkillAllowlistOptions(
+            toolName,
+            skillSelector,
+          ),
+        };
+    }
+  }
+}
+
+/** Singleton classifier instance. */
+export const skillLoadRiskClassifier = new SkillLoadRiskClassifier();

package/src/permissions/trust-client.ts

@@ -8,9 +8,14 @@
  * Both async and synchronous variants are exported. The sync variants
  * use `Bun.spawnSync` + `curl` to make blocking HTTP calls — acceptable
  * for user-initiated write operations that are infrequent.
+ *
+ * All rule-returning endpoints parse response payloads through the shared
+ * `parseTrustRule` canonical parser so the client never returns unparsed
+ * or untyped raw rule objects.
  */
 
 import type { TrustRule } from "@vellumai/ces-contracts";
+import { parseTrustRule } from "@vellumai/ces-contracts";
 
 import { getGatewayInternalBaseUrl } from "../config/env.js";
 import { mintEdgeRelayToken } from "../runtime/auth/token-service.js";
@@ -165,32 +170,58 @@ function requestSync<T>(method: string, path: string, body?: unknown): T {
   }
 }
 
+// ---------------------------------------------------------------------------
+// Response parsing helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a raw rule object from a gateway response through the shared
+ * canonical parser. Ensures the trust client never returns unparsed or
+ * untyped rule objects, regardless of what the gateway sends back.
+ */
+function parseRuleResponse(raw: unknown): TrustRule {
+  if (raw == null || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error("Trust rule response is not a valid object");
+  }
+  const { rule } = parseTrustRule(raw as Record<string, unknown>);
+  return rule as TrustRule;
+}
+
+/**
+ * Parse an array of raw rule objects from a gateway response.
+ */
+function parseRulesResponse(raw: unknown[]): TrustRule[] {
+  return raw.map((r) => parseRuleResponse(r));
+}
+
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
 
 /** Fetch all trust rules from the gateway. */
 export async function getAllRules(): Promise<TrustRule[]> {
-  const data = await request<{ rules: TrustRule[] }>("GET", "/v1/trust-rules");
-  return data.rules;
+  const data = await request<{ rules: unknown[] }>("GET", "/v1/trust-rules");
+  return parseRulesResponse(data.rules);
 }
 
 /** Create a new trust rule. */
 export async function addRule(params: {
   tool: string;
   pattern: string;
-  scope: string;
+  scope?: string;
   decision?: TrustRule["decision"];
   priority?: number;
-  allowHighRisk?: boolean;
   executionTarget?: string;
 }): Promise<TrustRule> {
-  const data = await request<{ rule: TrustRule }>(
+  // Only include scope in the request body if provided.
+  const { scope, ...rest } = params;
+  const body = scope != null ? { ...rest, scope } : rest;
+  const data = await request<{ rule: unknown }>(
     "POST",
     "/v1/trust-rules",
-    params,
+    body,
   );
-  return data.rule;
+  return parseRuleResponse(data.rule);
 }
 
 /** Update an existing trust rule by ID. */
@@ -202,16 +233,15 @@ export async function updateRule(
     scope?: string;
     decision?: TrustRule["decision"];
     priority?: number;
-    allowHighRisk?: boolean;
     executionTarget?: string;
   },
 ): Promise<TrustRule> {
-  const data = await request<{ rule: TrustRule }>(
+  const data = await request<{ rule: unknown }>(
     "PATCH",
     `/v1/trust-rules/${encodeURIComponent(id)}`,
     updates,
   );
-  return data.rule;
+  return parseRuleResponse(data.rule);
 }
 
 /** Remove a trust rule by ID. Returns true if the rule was found and deleted. */
@@ -245,11 +275,11 @@ export async function findMatchingRule(
     commands: candidates.join(","),
     scope,
   });
-  const data = await request<{ rule: TrustRule | null }>(
+  const data = await request<{ rule: unknown | null }>(
     "GET",
     `/v1/trust-rules/match?${params.toString()}`,
   );
-  return data.rule;
+  return data.rule != null ? parseRuleResponse(data.rule) : null;
 }
 
 /** Accept the starter approval bundle, seeding common low-risk allow rules. */
@@ -266,26 +296,24 @@ export async function acceptStarterBundle(): Promise<AcceptStarterBundleResult>
 
 /** Fetch all trust rules from the gateway (synchronous). */
 export function getAllRulesSync(): TrustRule[] {
-  const data = requestSync<{ rules: TrustRule[] }>("GET", "/v1/trust-rules");
-  return data.rules;
+  const data = requestSync<{ rules: unknown[] }>("GET", "/v1/trust-rules");
+  return parseRulesResponse(data.rules);
 }
 
 /** Create a new trust rule (synchronous). */
 export function addRuleSync(params: {
   tool: string;
   pattern: string;
-  scope: string;
+  scope?: string;
   decision?: TrustRule["decision"];
   priority?: number;
-  allowHighRisk?: boolean;
   executionTarget?: string;
 }): TrustRule {
-  const data = requestSync<{ rule: TrustRule }>(
-    "POST",
-    "/v1/trust-rules",
-    params,
-  );
-  return data.rule;
+  // Only include scope in the request body if provided.
+  const { scope, ...rest } = params;
+  const body = scope != null ? { ...rest, scope } : rest;
+  const data = requestSync<{ rule: unknown }>("POST", "/v1/trust-rules", body);
+  return parseRuleResponse(data.rule);
 }
 
 /** Update an existing trust rule by ID (synchronous). */
@@ -297,16 +325,15 @@ export function updateRuleSync(
     scope?: string;
     decision?: TrustRule["decision"];
     priority?: number;
-    allowHighRisk?: boolean;
     executionTarget?: string;
   },
 ): TrustRule {
-  const data = requestSync<{ rule: TrustRule }>(
+  const data = requestSync<{ rule: unknown }>(
     "PATCH",
     `/v1/trust-rules/${encodeURIComponent(id)}`,
     updates,
   );
-  return data.rule;
+  return parseRuleResponse(data.rule);
 }
 
 /** Remove a trust rule by ID (synchronous). Returns true if deleted. */