@vellumai/assistant 0.6.4 → 0.6.5

package/src/permissions/trust-store-interface.ts

@@ -45,11 +45,7 @@ export interface TrustStoreBackend {
   ): TrustRule | null;
 
   /** Find the first matching deny rule for a tool/command/scope. */
-  findDenyRule(
-    tool: string,
-    command: string,
-    scope: string,
-  ): TrustRule | null;
+  findDenyRule(tool: string, command: string, scope: string): TrustRule | null;
 
   /** Add a new trust rule and persist it. */
   addRule(
@@ -59,7 +55,6 @@ export interface TrustStoreBackend {
     decision?: "allow" | "deny" | "ask",
     priority?: number,
     options?: {
-      allowHighRisk?: boolean;
       executionTarget?: string;
     },
   ): TrustRule;

package/src/permissions/trust-store.ts

@@ -8,6 +8,12 @@ import {
 } from "node:fs";
 import { dirname, join } from "node:path";
 
+import {
+  parseTrustFileData,
+  parseTrustRule,
+  ruleScope,
+  SCOPED_TOOLS,
+} from "@vellumai/ces-contracts";
 import { Minimatch } from "minimatch";
 import { v4 as uuid } from "uuid";
 
@@ -31,6 +37,9 @@ export type { TrustStoreBackend } from "./trust-store-interface.js";
 
 const log = getLogger("trust-store");
 
+/** O(1) lookup set for scoped tool names. */
+const SCOPED_TOOLS_SET: ReadonlySet<string> = new Set(SCOPED_TOOLS);
+
 const TRUST_FILE_VERSION = 3;
 
 interface TrustFile {
@@ -151,7 +160,7 @@ function ruleOrder(a: TrustRule, b: TrustRule): number {
   if (b.priority !== a.priority) return b.priority - a.priority;
   if (a.decision !== b.decision) {
     // deny > ask > allow
-    const order = { deny: 0, ask: 1, allow: 2 };
+    const order: Record<string, number> = { deny: 0, ask: 1, allow: 2 };
     return (order[a.decision] ?? 2) - (order[b.decision] ?? 2);
   }
   return 0;
@@ -197,21 +206,39 @@ function backfillDefaults(rules: TrustRule[]): boolean {
     }
   }
 
-  // Migrate existing default rules whose priority, pattern, scope, decision,
-  // or allowHighRisk has changed in the template (e.g. host_bash pattern
-  // changed from '*' to '**', host tool priorities changed from 1000 to 50,
-  // workspace scope changed from getRootDir()+workspace to getWorkspaceDir()).
+  // Migrate existing default rules whose priority, pattern, scope, or decision
+  // has changed in the template (e.g. host_bash pattern changed from '*' to
+  // '**', host tool priorities changed from 1000 to 50, workspace scope
+  // changed from getRootDir()+workspace to getWorkspaceDir()).
+  //
+  // Also strip any leftover allowHighRisk fields from persisted default rules
+  // since the field has been replaced by runtime determination.
+  //
+  // Rules with `userModifiedAt` set are skipped — the user explicitly
+  // customized them and their override should be preserved across upgrades.
   for (const template of getDefaultRuleTemplates()) {
     if (existingIds.has(template.id)) {
       const rule = rules.find((r) => r.id === template.id);
+      if (!rule) continue;
+      // Strip legacy allowHighRisk from persisted default rules.
+      const ruleRecord = rule as unknown as Record<string, unknown>;
+      if ("allowHighRisk" in ruleRecord) {
+        delete ruleRecord.allowHighRisk;
+        changed = true;
+      }
       if (
-        rule &&
-        (rule.priority !== template.priority ||
-          rule.pattern !== template.pattern ||
-          rule.scope !== template.scope ||
-          rule.decision !== template.decision ||
-          rule.allowHighRisk !== template.allowHighRisk)
+        rule.priority !== template.priority ||
+        rule.pattern !== template.pattern ||
+        ruleScope(rule) !== (template.scope ?? "everywhere") ||
+        rule.decision !== template.decision
       ) {
+        if (rule.userModifiedAt != null) {
+          log.info(
+            { ruleId: rule.id, userModifiedAt: rule.userModifiedAt },
+            "Skipping migration of user-modified default rule",
+          );
+          continue;
+        }
         log.info(
           {
             ruleId: rule.id,
@@ -219,20 +246,17 @@ function backfillDefaults(rules: TrustRule[]): boolean {
             newPriority: template.priority,
             oldPattern: rule.pattern,
             newPattern: template.pattern,
-            oldScope: rule.scope,
-            newScope: template.scope,
+            oldScope: ruleScope(rule),
+            newScope: template.scope ?? "everywhere",
           },
           "Migrated default rule to updated template values",
         );
         rule.priority = template.priority;
         rule.pattern = template.pattern;
-        rule.scope = template.scope;
-        rule.decision = template.decision;
-        if (template.allowHighRisk != null) {
-          rule.allowHighRisk = template.allowHighRisk;
-        } else {
-          delete rule.allowHighRisk;
+        if (template.scope != null) {
+          rule.scope = template.scope;
         }
+        rule.decision = template.decision;
         changed = true;
       }
     }
@@ -240,19 +264,13 @@ function backfillDefaults(rules: TrustRule[]): boolean {
 
   for (const template of getDefaultRuleTemplates()) {
     if (!existingIds.has(template.id)) {
-      const rule: TrustRule = {
-        id: template.id,
-        tool: template.tool,
-        pattern: template.pattern,
-        scope: template.scope,
-        decision: template.decision,
-        priority: template.priority,
+      // Canonicalize through parseTrustRule so family-specific field
+      // validation is applied (consistent with fileAddRule/fileUpdateRule).
+      const { rule } = parseTrustRule({
+        ...template,
         createdAt: Date.now(),
-      };
-      if (template.allowHighRisk != null) {
-        rule.allowHighRisk = template.allowHighRisk;
-      }
-      rules.push(rule);
+      });
+      rules.push(rule as TrustRule);
       changed = true;
       log.info({ ruleId: template.id }, "Backfilled default trust rule");
     }
@@ -294,7 +312,6 @@ function loadFromDisk(): TrustRule[] {
         data.version === 1 ||
         data.version === 2
       ) {
-        rules = sanitizedRules;
         if (sanitizedRules.length < rawRules.length) {
           needsSave = true;
         }
@@ -306,6 +323,21 @@ function loadFromDisk(): TrustRule[] {
           );
         }
 
+        // Apply canonical parser for family-aware normalization.
+        // The parser strips fields that are invalid for a rule's tool family
+        // (e.g. executionTarget on URL rules) and coerces malformed values.
+        const { data: parsedData, normalized } = parseTrustFileData({
+          ...data,
+          rules: sanitizedRules,
+        });
+        // The contracts parser returns the union TrustRule type; our local
+        // TrustRule flattens the union with optional fields for backward
+        // compatibility. The structural overlap is safe to cast here.
+        rules = parsedData.rules as TrustRule[];
+        if (normalized) {
+          needsSave = true;
+        }
+
         // Strip legacy principal-scoped fields from persisted v3 rules.
         // Before the principal concept was removed, rules could carry
         // principalKind/principalId/principalVersion which acted as scope
@@ -400,31 +432,37 @@ function fileAddRule(
   decision: "allow" | "deny" | "ask" = "allow",
   priority: number = 100,
   options?: {
-    allowHighRisk?: boolean;
     executionTarget?: string;
   },
 ): TrustRule {
   if (tool.startsWith("__internal:"))
     throw new Error(`Cannot create internal pseudo-rule via addRule: ${tool}`);
-  // Re-read from disk to avoid lost updates if another call modified rules
-  // between our last read and now (e.g. two rapid trust rule additions).
-  cachedRules = null;
-  const rules = [...getRules()];
-  const rule: TrustRule = {
+
+  // Canonicalize through the shared parser so fields invalid for the tool's
+  // family are stripped before persistence, regardless of which callsite
+  // invoked addRule. Only include scope for scoped tools — non-scoped tools
+  // don't carry a scope field.
+  const rawRule: Record<string, unknown> = {
     id: uuid(),
     tool,
     pattern,
-    scope,
     decision,
     priority,
     createdAt: Date.now(),
   };
-  if (options?.allowHighRisk != null) {
-    rule.allowHighRisk = options.allowHighRisk;
+  if (SCOPED_TOOLS_SET.has(tool)) {
+    rawRule.scope = scope;
   }
   if (options?.executionTarget != null) {
-    rule.executionTarget = options.executionTarget;
+    rawRule.executionTarget = options.executionTarget;
   }
+  const { rule: canonical } = parseTrustRule(rawRule);
+  const rule = canonical as TrustRule;
+
+  // Re-read from disk to avoid lost updates if another call modified rules
+  // between our last read and now (e.g. two rapid trust rule additions).
+  cachedRules = null;
+  const rules = [...getRules()];
   rules.push(rule);
   rules.sort(ruleOrder);
   cachedRules = rules;
@@ -445,9 +483,6 @@ function fileUpdateRule(
     priority?: number;
   },
 ): TrustRule {
-  const defaultIds = new Set(getDefaultRuleTemplates().map((t) => t.id));
-  if (defaultIds.has(id))
-    throw new Error(`Cannot modify default trust rule: ${id}`);
   if (updates.tool?.startsWith("__internal:"))
     throw new Error(
       `Cannot update tool to internal pseudo-rule: ${updates.tool}`,
@@ -458,12 +493,45 @@ function fileUpdateRule(
   const rules = [...getRules()];
   const index = rules.findIndex((r) => r.id === id);
   if (index === -1) throw new Error(`Trust rule not found: ${id}`);
-  const rule = { ...rules[index] };
-  if (updates.tool != null) rule.tool = updates.tool;
-  if (updates.pattern != null) rule.pattern = updates.pattern;
-  if (updates.scope != null) rule.scope = updates.scope;
-  if (updates.decision != null) rule.decision = updates.decision;
-  if (updates.priority != null) rule.priority = updates.priority;
+  const merged = { ...rules[index] };
+  if (updates.tool != null) merged.tool = updates.tool;
+  if (updates.pattern != null) merged.pattern = updates.pattern;
+  // Only apply scope updates for scoped tools — non-scoped tools ignore scope.
+  const effectiveTool = updates.tool ?? merged.tool;
+  if (updates.scope != null && SCOPED_TOOLS_SET.has(effectiveTool)) {
+    merged.scope = updates.scope;
+  }
+  if (updates.decision != null) merged.decision = updates.decision;
+  if (updates.priority != null) merged.priority = updates.priority;
+
+  // Mark default rules with userModifiedAt so backfillDefaults() preserves
+  // the user's customization across upgrades instead of overwriting it.
+  // Only set the timestamp when the merged result actually diverges from the
+  // template — a no-op PATCH (same values) should not permanently opt a rule
+  // out of future template migrations.
+  const templates = getDefaultRuleTemplates();
+  const template = templates.find((t) => t.id === id);
+  if (template) {
+    const diverges =
+      merged.tool !== template.tool ||
+      merged.pattern !== template.pattern ||
+      ruleScope(merged) !== (template.scope ?? "everywhere") ||
+      merged.decision !== template.decision ||
+      merged.priority !== template.priority;
+    if (diverges) {
+      merged.userModifiedAt = Date.now();
+    } else {
+      // Rule matches the template again — clear the override marker so
+      // future template changes are applied normally.
+      delete merged.userModifiedAt;
+    }
+  }
+
+  // Canonicalize through parseTrustRule so that fields invalid for the
+  // (potentially changed) tool family are stripped. For example, if a rule's
+  // tool is changed from "bash" to "web_fetch", executionTarget is dropped
+  // because URL-family tools don't support target scoping.
+  const { rule } = parseTrustRule(merged as unknown as Record<string, unknown>);
   rules[index] = rule;
   rules.sort(ruleOrder);
   cachedRules = rules;
@@ -514,7 +582,7 @@ function findRuleByDecision(
     if (rule.decision !== decision) continue;
     const compiled = getCompiledPattern(rule.pattern);
     if (!compiled || !compiled.match(command)) continue;
-    if (!matchesScope(rule.scope, scope)) continue;
+    if (!matchesScope(ruleScope(rule), scope)) continue;
     return rule;
   }
   return null;
@@ -525,6 +593,10 @@ function findRuleByDecision(
  *
  * If the rule does not specify an executionTarget it matches any target
  * (wildcard). If specified, it must match exactly.
+ *
+ * Not all trust rule families carry `executionTarget` — URL, managed-skill,
+ * and skill-load rules never have it. For those families the check is a
+ * no-op (wildcard match).
  */
 function matchesExecutionTarget(rule: TrustRule, ctx?: PolicyContext): boolean {
   if (rule.executionTarget == null) return true;
@@ -561,7 +633,7 @@ function fileFindHighestPriorityRule(
 
   for (const rule of allRules) {
     if (rule.tool !== tool) continue;
-    if (!matchesScope(rule.scope, scope)) continue;
+    if (!matchesScope(ruleScope(rule), scope)) continue;
     if (!matchesExecutionTarget(rule, ctx)) continue;
     const compiled = getCompiledPattern(rule.pattern);
     if (!compiled) continue;
@@ -914,7 +986,7 @@ class GatewayTrustStoreAdapter implements TrustStoreBackend {
 
     for (const rule of allRules) {
       if (rule.tool !== tool) continue;
-      if (!matchesScope(rule.scope, scope)) continue;
+      if (!matchesScope(ruleScope(rule), scope)) continue;
       if (!matchesExecutionTarget(rule, ctx)) continue;
       const compiled = this.getCompiledPattern(rule.pattern);
       if (!compiled) continue;
@@ -938,7 +1010,7 @@ class GatewayTrustStoreAdapter implements TrustStoreBackend {
       if (rule.decision !== "allow") continue;
       const compiled = this.getCompiledPattern(rule.pattern);
       if (!compiled || !compiled.match(command)) continue;
-      if (!matchesScope(rule.scope, scope)) continue;
+      if (!matchesScope(ruleScope(rule), scope)) continue;
       return rule;
     }
     return null;
@@ -951,7 +1023,7 @@ class GatewayTrustStoreAdapter implements TrustStoreBackend {
       if (rule.decision !== "deny") continue;
       const compiled = this.getCompiledPattern(rule.pattern);
       if (!compiled || !compiled.match(command)) continue;
-      if (!matchesScope(rule.scope, scope)) continue;
+      if (!matchesScope(ruleScope(rule), scope)) continue;
       return rule;
     }
     return null;
@@ -964,7 +1036,6 @@ class GatewayTrustStoreAdapter implements TrustStoreBackend {
     decision: "allow" | "deny" | "ask" = "allow",
     priority: number = 100,
     options?: {
-      allowHighRisk?: boolean;
       executionTarget?: string;
     },
   ): TrustRule {
@@ -972,15 +1043,39 @@ class GatewayTrustStoreAdapter implements TrustStoreBackend {
       throw new Error(
         `Cannot create internal pseudo-rule via addRule: ${tool}`,
       );
-    this.ensureInitialized();
-    const rule = trustClient.addRuleSync({
+
+    // Canonicalize through the shared parser so fields invalid for the tool's
+    // family are stripped before sending to the gateway.
+    const { rule: canonical } = parseTrustRule({
+      id: "",
       tool,
       pattern,
       scope,
       decision,
       priority,
-      allowHighRisk: options?.allowHighRisk,
-      executionTarget: options?.executionTarget,
+      createdAt: 0,
+      ...(options?.executionTarget != null
+        ? { executionTarget: options.executionTarget }
+        : {}),
+    });
+    const canonicalOpts: { executionTarget?: string } = {};
+    if ("executionTarget" in canonical) {
+      canonicalOpts.executionTarget = (
+        canonical as { executionTarget?: string }
+      ).executionTarget;
+    }
+
+    this.ensureInitialized();
+    const rule = trustClient.addRuleSync({
+      tool: canonical.tool,
+      pattern: canonical.pattern,
+      // Only send scope for scoped tools — non-scoped tools omit it.
+      ...(SCOPED_TOOLS_SET.has(canonical.tool)
+        ? { scope: ruleScope(canonical) }
+        : {}),
+      decision: canonical.decision,
+      priority: canonical.priority,
+      executionTarget: canonicalOpts.executionTarget,
     });
     // Update local cache
     this.rules = [...this.rules, rule].sort(ruleOrder);
@@ -1005,6 +1100,11 @@ class GatewayTrustStoreAdapter implements TrustStoreBackend {
         `Cannot update tool to internal pseudo-rule: ${updates.tool}`,
       );
     this.ensureInitialized();
+
+    // Send only the caller's partial updates to the gateway.  The gateway's
+    // own updateRule merges and canonicalizes via parseTrustRule, so doing a
+    // full-rule merge here against the local cache would risk overwriting
+    // concurrent edits with stale cached values.
     const rule = trustClient.updateRuleSync(id, updates);
     // Update local cache
     const idx = this.rules.findIndex((r) => r.id === id);
@@ -1139,7 +1239,6 @@ export function addRule(
   decision: "allow" | "deny" | "ask" = "allow",
   priority: number = 100,
   options?: {
-    allowHighRisk?: boolean;
     executionTarget?: string;
   },
 ): TrustRule {

package/src/permissions/types.ts

@@ -1,27 +1,30 @@
+import type { TrustRuleBase } from "@vellumai/ces-contracts";
+
+/**
+ * Re-exported TrustRule type from `@vellumai/ces-contracts`.
+ *
+ * The contracts package defines `TrustRule` as a discriminated union over tool
+ * families (scoped, URL, managed-skill, skill-load, generic). Some variants
+ * don't carry `executionTarget`. To maintain backward
+ * compatibility with existing callsites that access those fields on any rule,
+ * we flatten the union here by intersecting the base with the optional fields.
+ */
+export type TrustRule = TrustRuleBase & {
+  scope?: string;
+  executionTarget?: string;
+};
+
 export enum RiskLevel {
   Low = "low",
   Medium = "medium",
   High = "high",
 }
 
-export interface TrustRule {
-  id: string;
-  tool: string;
-  pattern: string;
-  scope: string;
-  decision: "allow" | "deny" | "ask";
-  priority: number;
-  createdAt: number;
-  executionTarget?: string;
-  allowHighRisk?: boolean;
-}
-
 export type UserDecision =
   | "allow"
   | "allow_10m"
   | "allow_conversation"
   | "always_allow"
-  | "always_allow_high_risk"
   | "deny"
   | "always_deny"
   | "temporary_override";
@@ -33,7 +36,6 @@ export function isAllowDecision(decision: UserDecision): boolean {
     decision === "allow_10m" ||
     decision === "allow_conversation" ||
     decision === "always_allow" ||
-    decision === "always_allow_high_risk" ||
     decision === "temporary_override"
   );
 }
@@ -60,4 +62,11 @@ export interface PolicyContext {
   executionTarget?: string;
   /** Ephemeral rules for task-scoped permissions — checked before persistent trust.json rules. */
   ephemeralRules?: TrustRule[];
+  /**
+   * Execution context for per-context threshold resolution.
+   * - "conversation": interactive client session (default)
+   * - "background": non-interactive guardian session (e.g. scheduled jobs)
+   * - "headless": non-interactive non-guardian session
+   */
+  executionContext?: "conversation" | "background" | "headless";
 }

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

@@ -0,0 +1,170 @@
+import { describe, expect, test } from "bun:test";
+
+import { WebRiskClassifier } from "./web-risk-classifier.js";
+
+// ── Helper ───────────────────────────────────────────────────────────────────
+
+function makeClassifier(): WebRiskClassifier {
+  return new WebRiskClassifier();
+}
+
+// ── web_search ───────────────────────────────────────────────────────────────
+
+describe("web_search", () => {
+  test("always classified as low risk", async () => {
+    const classifier = makeClassifier();
+    const result = await classifier.classify({
+      toolName: "web_search",
+    });
+    expect(result.riskLevel).toBe("low");
+    expect(result.reason).toBe("Web search (read-only)");
+    expect(result.matchType).toBe("registry");
+    expect(result.scopeOptions).toEqual([]);
+  });
+
+  test("low risk even with url provided", async () => {
+    const classifier = makeClassifier();
+    const result = await classifier.classify({
+      toolName: "web_search",
+      url: "https://example.com",
+    });
+    expect(result.riskLevel).toBe("low");
+  });
+});
+
+// ── web_fetch ────────────────────────────────────────────────────────────────
+
+describe("web_fetch", () => {
+  test("default (no private network) is low risk", async () => {
+    const classifier = makeClassifier();
+    const result = await classifier.classify({
+      toolName: "web_fetch",
+    });
+    expect(result.riskLevel).toBe("low");
+    expect(result.reason).toBe("Web fetch (default)");
+    expect(result.matchType).toBe("registry");
+    expect(result.scopeOptions).toEqual([]);
+  });
+
+  test("allowPrivateNetwork=false is low risk", async () => {
+    const classifier = makeClassifier();
+    const result = await classifier.classify({
+      toolName: "web_fetch",
+      allowPrivateNetwork: false,
+    });
+    expect(result.riskLevel).toBe("low");
+    expect(result.reason).toBe("Web fetch (default)");
+  });
+
+  test("allowPrivateNetwork=undefined is low risk", async () => {
+    const classifier = makeClassifier();
+    const result = await classifier.classify({
+      toolName: "web_fetch",
+      allowPrivateNetwork: undefined,
+    });
+    expect(result.riskLevel).toBe("low");
+  });
+
+  test("allowPrivateNetwork=true is high risk", async () => {
+    const classifier = makeClassifier();
+    const result = await classifier.classify({
+      toolName: "web_fetch",
+      allowPrivateNetwork: true,
+    });
+    expect(result.riskLevel).toBe("high");
+    expect(result.reason).toBe("Private network fetch");
+    expect(result.matchType).toBe("registry");
+    expect(result.scopeOptions).toEqual([]);
+  });
+
+  test("private network fetch with url", async () => {
+    const classifier = makeClassifier();
+    const result = await classifier.classify({
+      toolName: "web_fetch",
+      url: "http://192.168.1.1/admin",
+      allowPrivateNetwork: true,
+    });
+    expect(result.riskLevel).toBe("high");
+    expect(result.reason).toBe("Private network fetch");
+  });
+});
+
+// ── network_request ──────────────────────────────────────────────────────────
+
+describe("network_request", () => {
+  test("always classified as medium risk", async () => {
+    const classifier = makeClassifier();
+    const result = await classifier.classify({
+      toolName: "network_request",
+    });
+    expect(result.riskLevel).toBe("medium");
+    expect(result.reason).toBe("Network request (proxied credentials)");
+    expect(result.matchType).toBe("registry");
+    expect(result.scopeOptions).toEqual([]);
+  });
+
+  test("medium risk with url provided", async () => {
+    const classifier = makeClassifier();
+    const result = await classifier.classify({
+      toolName: "network_request",
+      url: "https://api.example.com/data",
+    });
+    expect(result.riskLevel).toBe("medium");
+  });
+
+  test("medium risk regardless of allowPrivateNetwork flag", async () => {
+    const classifier = makeClassifier();
+    const result = await classifier.classify({
+      toolName: "network_request",
+      allowPrivateNetwork: true,
+    });
+    expect(result.riskLevel).toBe("medium");
+    expect(result.reason).toBe("Network request (proxied credentials)");
+  });
+});
+
+// ── Allowlist options ────────────────────────────────────────────────────────
+// The web classifier intentionally does NOT produce allowlistOptions.
+// URL normalization for scope options is handled by the canonical
+// urlAllowlistStrategy in checker.ts (avoids circular import + divergent
+// normalization). These tests verify the classifier omits them.
+
+describe("allowlistOptions", () => {
+  test("web_fetch omits allowlistOptions (defers to canonical urlAllowlistStrategy)", async () => {
+    const classifier = makeClassifier();
+    const result = await classifier.classify({
+      toolName: "web_fetch",
+      url: "https://example.com/api/data?key=value",
+    });
+    expect(result.allowlistOptions).toBeUndefined();
+  });
+
+  test("network_request omits allowlistOptions", async () => {
+    const classifier = makeClassifier();
+    const result = await classifier.classify({
+      toolName: "network_request",
+      url: "https://api.example.com/v1/users",
+    });
+    expect(result.allowlistOptions).toBeUndefined();
+  });
+
+  test("web_search omits allowlistOptions", async () => {
+    const classifier = makeClassifier();
+    const result = await classifier.classify({
+      toolName: "web_search",
+    });
+    expect(result.allowlistOptions).toBeUndefined();
+  });
+});
+
+// ── Singleton ────────────────────────────────────────────────────────────────
+
+describe("singleton", () => {
+  test("webRiskClassifier is exported and functional", async () => {
+    const { webRiskClassifier } = await import("./web-risk-classifier.js");
+    const result = await webRiskClassifier.classify({
+      toolName: "web_search",
+    });
+    expect(result.riskLevel).toBe("low");
+  });
+});