@vellumai/credential-executor 0.6.4 → 0.6.5

package/node_modules/@vellumai/ces-contracts/package.json

@@ -9,7 +9,8 @@
     "./handles": "./src/handles.ts",
     "./grants": "./src/grants.ts",
     "./rpc": "./src/rpc.ts",
-    "./rendering": "./src/rendering.ts"
+    "./rendering": "./src/rendering.ts",
+    "./trust-rules": "./src/trust-rules.ts"
   },
   "scripts": {
     "typecheck": "bunx tsc --noEmit",

package/node_modules/@vellumai/ces-contracts/src/__tests__/trust-rules.test.ts

@@ -0,0 +1,471 @@
+/**
+ * Tests for trust-rule family types and canonical parsing/normalization.
+ *
+ * Verifies:
+ * 1. Scoped-rule parsing preserves executionTarget, strips allowHighRisk.
+ * 2. Non-scoped known-tool rules strip executionTarget and allowHighRisk.
+ * 3. Unknown-tool rules preserve executionTarget, strip allowHighRisk.
+ * 4. Normalization flag behavior signals when a re-save is warranted.
+ * 5. parseTrustFileData handles full trust file objects.
+ */
+
+import { describe, expect, test } from "bun:test";
+import {
+  isManagedSkillRule,
+  isScopedRule,
+  isSkillLoadRule,
+  isUrlRule,
+  parseTrustFileData,
+  parseTrustRule,
+  ruleScope,
+  SCOPED_TOOLS,
+  URL_TOOLS,
+  MANAGED_SKILL_TOOLS,
+  SKILL_LOAD_TOOL,
+} from "../trust-rules.js";
+import type {
+  GenericTrustRule,
+  ManagedSkillTrustRule,
+  ScopedTrustRule,
+  SkillLoadTrustRule,
+  TrustRule,
+  UrlTrustRule,
+} from "../trust-rules.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeRaw(overrides: Record<string, unknown> = {}): Record<string, unknown> {
+  return {
+    id: "test-rule-1",
+    tool: "bash",
+    pattern: "**",
+    scope: "everywhere",
+    decision: "allow",
+    priority: 100,
+    createdAt: 1700000000000,
+    ...overrides,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Scoped-rule parsing
+// ---------------------------------------------------------------------------
+
+describe("parseTrustRule — scoped tools", () => {
+  test.each([...SCOPED_TOOLS])("preserves executionTarget and strips allowHighRisk for %s", (tool) => {
+    const raw = makeRaw({
+      tool,
+      executionTarget: "container-a",
+      allowHighRisk: true,
+    });
+    const { rule, normalized } = parseTrustRule(raw);
+    // allowHighRisk triggers normalization
+    expect(normalized).toBe(true);
+    expect(rule.tool).toBe(tool);
+    expect((rule as ScopedTrustRule).executionTarget).toBe("container-a");
+    // allowHighRisk is stripped
+    expect("allowHighRisk" in rule).toBe(false);
+  });
+
+  test("scoped rule without optional fields is not normalized", () => {
+    const raw = makeRaw({ tool: "host_bash" });
+    const { rule, normalized } = parseTrustRule(raw);
+    expect(normalized).toBe(false);
+    expect(rule.tool).toBe("host_bash");
+    expect("executionTarget" in rule).toBe(false);
+    expect("allowHighRisk" in rule).toBe(false);
+  });
+
+  test("type guard isScopedRule narrows correctly", () => {
+    const { rule } = parseTrustRule(makeRaw({ tool: "file_write" }));
+    expect(isScopedRule(rule)).toBe(true);
+    expect(isUrlRule(rule)).toBe(false);
+    expect(isManagedSkillRule(rule)).toBe(false);
+    expect(isSkillLoadRule(rule)).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Non-scoped known-tool scope stripping
+// ---------------------------------------------------------------------------
+
+describe("parseTrustRule — URL tools strip invalid fields", () => {
+  test.each([...URL_TOOLS])(
+    "strips executionTarget and allowHighRisk on %s",
+    (tool) => {
+      const raw = makeRaw({
+        tool,
+        executionTarget: "should-be-stripped",
+        allowHighRisk: true,
+      });
+      const { rule, normalized } = parseTrustRule(raw);
+      expect(normalized).toBe(true);
+      expect(rule.tool).toBe(tool);
+      expect("executionTarget" in rule).toBe(false);
+      expect("allowHighRisk" in rule).toBe(false);
+    },
+  );
+
+  test("URL tool without invalid fields is not normalized", () => {
+    const raw = makeRaw({ tool: "web_fetch" });
+    const { rule, normalized } = parseTrustRule(raw);
+    expect(normalized).toBe(false);
+    expect(rule.tool).toBe("web_fetch");
+    // scope is stripped even though it was present in raw input
+    expect("scope" in rule).toBe(false);
+  });
+
+  test("URL tool with scope 'everywhere' strips scope without normalization flag", () => {
+    const raw = makeRaw({ tool: "web_fetch", scope: "everywhere" });
+    const { rule, normalized } = parseTrustRule(raw);
+    expect(normalized).toBe(false);
+    expect("scope" in rule).toBe(false);
+  });
+
+  test("URL tool with non-'everywhere' scope strips scope and sets normalized", () => {
+    const raw = makeRaw({ tool: "web_fetch", scope: "/some/dir" });
+    const { rule, normalized } = parseTrustRule(raw);
+    expect(normalized).toBe(true);
+    expect("scope" in rule).toBe(false);
+  });
+
+  test("type guard isUrlRule narrows correctly", () => {
+    const { rule } = parseTrustRule(makeRaw({ tool: "network_request" }));
+    expect(isUrlRule(rule)).toBe(true);
+    expect(isScopedRule(rule)).toBe(false);
+  });
+});
+
+describe("parseTrustRule — managed skill tools strip invalid fields", () => {
+  test.each([...MANAGED_SKILL_TOOLS])(
+    "strips executionTarget and allowHighRisk on %s",
+    (tool) => {
+      const raw = makeRaw({
+        tool,
+        executionTarget: "x",
+        allowHighRisk: false,
+      });
+      const { rule, normalized } = parseTrustRule(raw);
+      expect(normalized).toBe(true);
+      expect("executionTarget" in rule).toBe(false);
+      expect("allowHighRisk" in rule).toBe(false);
+    },
+  );
+
+  test("managed skill tool with scope 'everywhere' strips scope without normalization flag", () => {
+    const raw = makeRaw({ tool: "scaffold_managed_skill", scope: "everywhere" });
+    const { rule, normalized } = parseTrustRule(raw);
+    expect(normalized).toBe(false);
+    expect("scope" in rule).toBe(false);
+  });
+
+  test("managed skill tool with non-'everywhere' scope strips scope and sets normalized", () => {
+    const raw = makeRaw({ tool: "delete_managed_skill", scope: "/some/dir" });
+    const { rule, normalized } = parseTrustRule(raw);
+    expect(normalized).toBe(true);
+    expect("scope" in rule).toBe(false);
+  });
+
+  test("type guard isManagedSkillRule narrows correctly", () => {
+    const { rule } = parseTrustRule(makeRaw({ tool: "scaffold_managed_skill" }));
+    expect(isManagedSkillRule(rule)).toBe(true);
+    expect(isScopedRule(rule)).toBe(false);
+  });
+});
+
+describe("parseTrustRule — skill_load strips invalid fields", () => {
+  test("strips executionTarget and allowHighRisk on skill_load", () => {
+    const raw = makeRaw({
+      tool: SKILL_LOAD_TOOL,
+      executionTarget: "container-b",
+      allowHighRisk: true,
+    });
+    const { rule, normalized } = parseTrustRule(raw);
+    expect(normalized).toBe(true);
+    expect(rule.tool).toBe(SKILL_LOAD_TOOL);
+    expect("executionTarget" in rule).toBe(false);
+    expect("allowHighRisk" in rule).toBe(false);
+  });
+
+  test("skill_load without invalid fields is not normalized", () => {
+    const raw = makeRaw({ tool: SKILL_LOAD_TOOL, pattern: "skill_load:*" });
+    const { rule, normalized } = parseTrustRule(raw);
+    expect(normalized).toBe(false);
+    expect(rule.tool).toBe(SKILL_LOAD_TOOL);
+    expect("scope" in rule).toBe(false);
+  });
+
+  test("skill_load with scope 'everywhere' strips scope without normalization flag", () => {
+    const raw = makeRaw({ tool: SKILL_LOAD_TOOL, scope: "everywhere" });
+    const { rule, normalized } = parseTrustRule(raw);
+    expect(normalized).toBe(false);
+    expect("scope" in rule).toBe(false);
+  });
+
+  test("skill_load with non-'everywhere' scope strips scope and sets normalized", () => {
+    const raw = makeRaw({ tool: SKILL_LOAD_TOOL, scope: "/some/dir" });
+    const { rule, normalized } = parseTrustRule(raw);
+    expect(normalized).toBe(true);
+    expect("scope" in rule).toBe(false);
+  });
+
+  test("type guard isSkillLoadRule narrows correctly", () => {
+    const { rule } = parseTrustRule(makeRaw({ tool: SKILL_LOAD_TOOL }));
+    expect(isSkillLoadRule(rule)).toBe(true);
+    expect(isScopedRule(rule)).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Unknown-tool preservation
+// ---------------------------------------------------------------------------
+
+describe("parseTrustRule — unknown tools", () => {
+  test("preserves executionTarget but strips allowHighRisk for unknown tools", () => {
+    const raw = makeRaw({
+      tool: "future_tool_v99",
+      executionTarget: "edge-worker",
+      allowHighRisk: true,
+    });
+    const { rule, normalized } = parseTrustRule(raw);
+    // allowHighRisk triggers normalization
+    expect(normalized).toBe(true);
+    expect(rule.tool).toBe("future_tool_v99");
+    expect((rule as GenericTrustRule).executionTarget).toBe("edge-worker");
+    expect("allowHighRisk" in rule).toBe(false);
+  });
+
+  test("unknown tool without optional fields is not normalized", () => {
+    const raw = makeRaw({ tool: "computer_use_click" });
+    const { rule, normalized } = parseTrustRule(raw);
+    expect(normalized).toBe(false);
+    expect(rule.tool).toBe("computer_use_click");
+    expect("scope" in rule).toBe(false);
+    expect("executionTarget" in rule).toBe(false);
+    expect("allowHighRisk" in rule).toBe(false);
+  });
+
+  test("unknown tool with non-everywhere scope strips scope and sets normalized", () => {
+    const raw = makeRaw({ tool: "future_tool_v99", scope: "/some/dir" });
+    const { rule, normalized } = parseTrustRule(raw);
+    expect(normalized).toBe(true);
+    expect("scope" in rule).toBe(false);
+  });
+
+  test("all type guards return false for generic rules", () => {
+    const { rule } = parseTrustRule(makeRaw({ tool: "some_new_tool" }));
+    expect(isScopedRule(rule)).toBe(false);
+    expect(isUrlRule(rule)).toBe(false);
+    expect(isManagedSkillRule(rule)).toBe(false);
+    expect(isSkillLoadRule(rule)).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Normalization flag behavior
+// ---------------------------------------------------------------------------
+
+describe("parseTrustRule — normalization flag", () => {
+  test("normalized is false when no changes needed (no allowHighRisk)", () => {
+    const raw = makeRaw({ tool: "host_bash" });
+    const { normalized } = parseTrustRule(raw);
+    expect(normalized).toBe(false);
+  });
+
+  test("normalized is true when allowHighRisk is present (stripped)", () => {
+    const raw = makeRaw({ tool: "host_bash", allowHighRisk: true });
+    const { normalized } = parseTrustRule(raw);
+    expect(normalized).toBe(true);
+  });
+
+  test("normalized is true when URL tool has allowHighRisk (stripped)", () => {
+    const raw = makeRaw({ tool: "web_fetch", allowHighRisk: true });
+    const { normalized } = parseTrustRule(raw);
+    expect(normalized).toBe(true);
+  });
+
+  test("normalized is true when decision is coerced", () => {
+    const raw = makeRaw({ tool: "bash", decision: "invalid_decision" });
+    const { rule, normalized } = parseTrustRule(raw);
+    expect(normalized).toBe(true);
+    expect(rule.decision).toBe("ask");
+  });
+
+  test("empty executionTarget string is not preserved on scoped rules", () => {
+    const raw = makeRaw({ tool: "bash", executionTarget: "" });
+    const { rule, normalized } = parseTrustRule(raw);
+    expect(normalized).toBe(false);
+    expect("executionTarget" in rule).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// ruleScope helper
+// ---------------------------------------------------------------------------
+
+describe("ruleScope", () => {
+  test("returns scope for scoped rules", () => {
+    const { rule } = parseTrustRule(makeRaw({ tool: "bash", scope: "/projects" }));
+    expect(ruleScope(rule)).toBe("/projects");
+  });
+
+  test("returns 'everywhere' for non-scoped rules without scope", () => {
+    const { rule } = parseTrustRule(makeRaw({ tool: "web_fetch" }));
+    expect("scope" in rule).toBe(false);
+    expect(ruleScope(rule)).toBe("everywhere");
+  });
+
+  test("returns 'everywhere' for generic rules (scope is stripped)", () => {
+    const { rule } = parseTrustRule(makeRaw({ tool: "future_tool", scope: "/custom" }));
+    expect("scope" in rule).toBe(false);
+    expect(ruleScope(rule)).toBe("everywhere");
+  });
+
+  test("returns 'everywhere' for scoped rules with default scope", () => {
+    const { rule } = parseTrustRule(makeRaw({ tool: "file_read", scope: "everywhere" }));
+    expect(ruleScope(rule)).toBe("everywhere");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// parseTrustFileData
+// ---------------------------------------------------------------------------
+
+describe("parseTrustFileData", () => {
+  test("parses a valid trust file with mixed rule families", () => {
+    const raw = {
+      version: 3,
+      starterBundleAccepted: true,
+      rules: [
+        makeRaw({ id: "r1", tool: "bash" }),
+        makeRaw({ id: "r2", tool: "web_fetch", pattern: "web_fetch:https://example.com/*" }),
+        makeRaw({ id: "r3", tool: "skill_load", pattern: "skill_load:*" }),
+      ],
+    };
+    const { data, normalized } = parseTrustFileData(raw);
+    expect(normalized).toBe(false);
+    expect(data.version).toBe(3);
+    expect(data.starterBundleAccepted).toBe(true);
+    expect(data.rules).toHaveLength(3);
+    expect(data.rules[0].tool).toBe("bash");
+    expect(data.rules[1].tool).toBe("web_fetch");
+    expect(data.rules[2].tool).toBe("skill_load");
+  });
+
+  test("reports normalized when any rule is modified", () => {
+    const raw = {
+      version: 3,
+      rules: [
+        makeRaw({ id: "r1", tool: "bash" }),
+        // This rule has an invalid field for its family
+        makeRaw({ id: "r2", tool: "web_fetch", executionTarget: "stale" }),
+      ],
+    };
+    const { data, normalized } = parseTrustFileData(raw);
+    expect(normalized).toBe(true);
+    expect(data.rules).toHaveLength(2);
+    expect("executionTarget" in data.rules[1]).toBe(false);
+  });
+
+  test("reports normalized when allowHighRisk is present (stripped)", () => {
+    const raw = {
+      version: 3,
+      rules: [
+        makeRaw({ id: "r1", tool: "bash", allowHighRisk: true }),
+      ],
+    };
+    const { data, normalized } = parseTrustFileData(raw);
+    expect(normalized).toBe(true);
+    expect(data.rules).toHaveLength(1);
+    expect("allowHighRisk" in data.rules[0]).toBe(false);
+  });
+
+  test("skips null/non-object entries and flags as normalized", () => {
+    const raw = {
+      version: 3,
+      rules: [null, 42, makeRaw({ id: "r1", tool: "bash" })],
+    };
+    const { data, normalized } = parseTrustFileData(raw);
+    expect(normalized).toBe(true);
+    expect(data.rules).toHaveLength(1);
+    expect(data.rules[0].id).toBe("r1");
+  });
+
+  test("handles missing rules array", () => {
+    const raw = { version: 3 };
+    const { data, normalized } = parseTrustFileData(raw);
+    expect(normalized).toBe(false);
+    expect(data.rules).toEqual([]);
+  });
+
+  test("handles missing version", () => {
+    const raw = { rules: [] };
+    const { data } = parseTrustFileData(raw);
+    expect(data.version).toBe(0);
+  });
+
+  test("starterBundleAccepted defaults to undefined when not true", () => {
+    const raw = { version: 3, rules: [], starterBundleAccepted: false };
+    const { data } = parseTrustFileData(raw);
+    expect(data.starterBundleAccepted).toBeUndefined();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Type-level smoke tests (compile-time only — no runtime assertions)
+// ---------------------------------------------------------------------------
+
+describe("type-level compatibility", () => {
+  test("TrustRule union is assignable from all family interfaces", () => {
+    // These assignments verify that each family interface satisfies TrustRule.
+    // If any interface breaks the union, TypeScript will fail at compile time.
+    const scoped: ScopedTrustRule = {
+      id: "s1",
+      tool: "bash",
+      pattern: "**",
+      scope: "everywhere",
+      decision: "allow",
+      priority: 50,
+      createdAt: 0,
+      executionTarget: "host",
+    };
+    const url: UrlTrustRule = {
+      id: "u1",
+      tool: "web_fetch",
+      pattern: "web_fetch:*",
+      decision: "allow",
+      priority: 90,
+      createdAt: 0,
+    };
+    const managed: ManagedSkillTrustRule = {
+      id: "m1",
+      tool: "scaffold_managed_skill",
+      pattern: "scaffold_managed_skill:*",
+      decision: "ask",
+      priority: 1000,
+      createdAt: 0,
+    };
+    const skillLoad: SkillLoadTrustRule = {
+      id: "sl1",
+      tool: "skill_load",
+      pattern: "skill_load:*",
+      decision: "allow",
+      priority: 100,
+      createdAt: 0,
+    };
+    const generic: GenericTrustRule = {
+      id: "g1",
+      tool: "computer_use_click",
+      pattern: "**",
+      decision: "ask",
+      priority: 1000,
+      createdAt: 0,
+    };
+
+    // All should be assignable to TrustRule
+    const rules: TrustRule[] = [scoped, url, managed, skillLoad, generic];
+    expect(rules).toHaveLength(5);
+  });
+});

package/node_modules/@vellumai/ces-contracts/src/trust-rules.ts

@@ -4,6 +4,22 @@
  * These are extracted from `assistant/src/permissions/types.ts` and
  * `assistant/src/permissions/trust-store.ts` so that both packages can
  * reference a single canonical definition.
+ *
+ * Tools are grouped into "families" based on how their permission candidates
+ * are constructed and matched:
+ *
+ * - **Scoped**: tools whose candidates include a filesystem path and obey
+ *   directory-boundary scope constraints (`file_read`, `file_write`,
+ *   `file_edit`, `host_file_read`, `host_file_write`, `host_file_edit`,
+ *   `bash`, `host_bash`).
+ * - **URL**: tools whose candidates include a URL (`web_fetch`,
+ *   `network_request`).
+ * - **Managed skill**: tools that manage first-party skill packages
+ *   (`scaffold_managed_skill`, `delete_managed_skill`).
+ * - **Skill load**: the `skill_load` tool, which uses a distinct candidate
+ *   namespace (`skill_load:selector` or `skill_load_dynamic:selector`).
+ * - **Generic**: everything else (computer-use tools, UI surface tools,
+ *   recall, skill_execute, etc.).
  */
 
 // ---------------------------------------------------------------------------
@@ -14,19 +30,349 @@
 export type TrustDecision = "allow" | "deny" | "ask";
 
 // ---------------------------------------------------------------------------
-// Trust rule
+// Tool family constants
+// ---------------------------------------------------------------------------
+
+/**
+ * Tools whose permission candidates are scoped to a filesystem path and obey
+ * directory-boundary scope constraints.
+ */
+export const SCOPED_TOOLS = [
+  "file_read",
+  "file_write",
+  "file_edit",
+  "host_file_read",
+  "host_file_write",
+  "host_file_edit",
+  "bash",
+  "host_bash",
+] as const;
+
+/**
+ * Tools whose permission candidates include a URL.
+ */
+export const URL_TOOLS = ["web_fetch", "network_request"] as const;
+
+/**
+ * Tools that manage first-party skill packages (scaffold/delete).
+ */
+export const MANAGED_SKILL_TOOLS = [
+  "scaffold_managed_skill",
+  "delete_managed_skill",
+] as const;
+
+/**
+ * The skill_load tool name. Separated from the array constants because
+ * skill_load is a singleton, not a family with multiple members.
+ */
+export const SKILL_LOAD_TOOL = "skill_load" as const;
+
+/** Set for O(1) lookups when classifying tool names. */
+const SCOPED_TOOLS_SET: ReadonlySet<string> = new Set(SCOPED_TOOLS);
+const URL_TOOLS_SET: ReadonlySet<string> = new Set(URL_TOOLS);
+const MANAGED_SKILL_TOOLS_SET: ReadonlySet<string> = new Set(
+  MANAGED_SKILL_TOOLS,
+);
+
+// ---------------------------------------------------------------------------
+// Trust rule — base and family-specific variants
 // ---------------------------------------------------------------------------
 
-export interface TrustRule {
+/** Fields shared by all trust rule variants. */
+export interface TrustRuleBase {
   id: string;
   tool: string;
   pattern: string;
-  scope: string;
   decision: TrustDecision;
   priority: number;
   createdAt: number;
+  /**
+   * Set when a user explicitly modifies a default trust rule.
+   * When present, `backfillDefaults()` will not overwrite the rule
+   * with updated template values on upgrade — preserving the user's
+   * customization.
+   */
+  userModifiedAt?: number;
+}
+
+/**
+ * A trust rule for a scoped tool (filesystem-path-based candidates).
+ *
+ * Scoped rules may carry `executionTarget` to constrain matching to a
+ * specific execution environment.
+ */
+export interface ScopedTrustRule extends TrustRuleBase {
+  tool: (typeof SCOPED_TOOLS)[number];
+  scope: string;
   executionTarget?: string;
-  allowHighRisk?: boolean;
+}
+
+/**
+ * A trust rule for a URL-based tool.
+ *
+ * URL rules do not use `executionTarget`.
+ */
+export interface UrlTrustRule extends TrustRuleBase {
+  tool: (typeof URL_TOOLS)[number];
+}
+
+/**
+ * A trust rule for a managed-skill tool (scaffold/delete).
+ */
+export interface ManagedSkillTrustRule extends TrustRuleBase {
+  tool: (typeof MANAGED_SKILL_TOOLS)[number];
+}
+
+/**
+ * A trust rule for the `skill_load` tool.
+ */
+export interface SkillLoadTrustRule extends TrustRuleBase {
+  tool: typeof SKILL_LOAD_TOOL;
+}
+
+/**
+ * A trust rule for any tool that doesn't belong to a known family.
+ *
+ * Generic rules preserve `executionTarget` for backward compatibility —
+ * existing rules for unknown/new tools may carry this field.
+ * Scope is intentionally absent: new tools that need scope must be explicitly
+ * added to `SCOPED_TOOLS` and use `ScopedTrustRule`.
+ */
+export interface GenericTrustRule extends TrustRuleBase {
+  tool: string;
+  executionTarget?: string;
+}
+
+/**
+ * Discriminated union of all trust rule families.
+ *
+ * The union is discriminated on the `tool` field: known tool names narrow to
+ * the corresponding family variant, while unknown tool names fall through to
+ * `GenericTrustRule`.
+ *
+ * For backward compatibility, `TrustRule` remains the single type that all
+ * existing code uses. The family-specific interfaces exist so that new code
+ * can narrow the type when it knows the tool family.
+ */
+export type TrustRule =
+  | ScopedTrustRule
+  | UrlTrustRule
+  | ManagedSkillTrustRule
+  | SkillLoadTrustRule
+  | GenericTrustRule;
+
+// ---------------------------------------------------------------------------
+// Type guards
+// ---------------------------------------------------------------------------
+
+/** Narrow a TrustRule to a ScopedTrustRule. */
+export function isScopedRule(rule: TrustRule): rule is ScopedTrustRule {
+  return SCOPED_TOOLS_SET.has(rule.tool);
+}
+
+/** Narrow a TrustRule to a UrlTrustRule. */
+export function isUrlRule(rule: TrustRule): rule is UrlTrustRule {
+  return URL_TOOLS_SET.has(rule.tool);
+}
+
+/** Narrow a TrustRule to a ManagedSkillTrustRule. */
+export function isManagedSkillRule(
+  rule: TrustRule,
+): rule is ManagedSkillTrustRule {
+  return MANAGED_SKILL_TOOLS_SET.has(rule.tool);
+}
+
+/** Narrow a TrustRule to a SkillLoadTrustRule. */
+export function isSkillLoadRule(rule: TrustRule): rule is SkillLoadTrustRule {
+  return rule.tool === SKILL_LOAD_TOOL;
+}
+
+// ---------------------------------------------------------------------------
+// Scope helper
+// ---------------------------------------------------------------------------
+
+/**
+ * Return the effective scope for any trust rule. Only scoped rules carry a
+ * `scope` field; all other rule families return `"everywhere"`.
+ */
+export function ruleScope(rule: TrustRule): string {
+  if (isScopedRule(rule)) {
+    return rule.scope;
+  }
+  return "everywhere";
+}
+
+// ---------------------------------------------------------------------------
+// Canonical parse / normalize
+// ---------------------------------------------------------------------------
+
+/**
+ * Result of parsing a raw trust rule object. Includes the normalized rule
+ * and a flag indicating whether any normalization occurred (so callers can
+ * trigger a re-save of the trust file).
+ */
+export interface ParsedTrustRule {
+  rule: TrustRule;
+  /** True if any fields were stripped or modified during normalization. */
+  normalized: boolean;
+}
+
+/**
+ * Parse and normalize a raw trust rule object into a canonical `TrustRule`.
+ *
+ * Normalization strips fields that are invalid for the rule's tool family:
+ * - URL rules: `executionTarget` and `scope` are stripped.
+ * - Managed skill rules: `executionTarget` and `scope` are stripped.
+ * - Skill load rules: `executionTarget` and `scope` are stripped.
+ * - Scoped rules: `scope` is preserved (defaulting to `"everywhere"`),
+ *   `executionTarget` is preserved when valid.
+ * - Generic (unknown) rules: `scope` is stripped (new tools that need scope
+ *   must be added to `SCOPED_TOOLS`); `executionTarget` is preserved for
+ *   forward compatibility.
+ * - All families: `allowHighRisk` is stripped (replaced by runtime
+ *   determination in checker.ts). Old trust.json files with `allowHighRisk`
+ *   are normalized on load.
+ */
+export function parseTrustRule(raw: Record<string, unknown>): ParsedTrustRule {
+  let normalized = false;
+
+  // Extract base fields with coercion for safety — mark normalized whenever
+  // a field is coerced to its default so callers know to re-save.
+  const id = typeof raw.id === "string" ? raw.id : ((normalized = true), "");
+  const tool =
+    typeof raw.tool === "string" ? raw.tool : ((normalized = true), "");
+  const pattern =
+    typeof raw.pattern === "string" ? raw.pattern : ((normalized = true), "");
+  const decision = isValidDecision(raw.decision)
+    ? raw.decision
+    : ((normalized = true), "ask" as const);
+  const priority =
+    typeof raw.priority === "number" ? raw.priority : ((normalized = true), 100);
+  const createdAt =
+    typeof raw.createdAt === "number"
+      ? raw.createdAt
+      : ((normalized = true), 0);
+  const userModifiedAt =
+    typeof raw.userModifiedAt === "number" ? raw.userModifiedAt : undefined;
+
+  // Build the base rule — scope is NOT included here; it is added only by
+  // the scoped and generic branches below.
+  const base: TrustRuleBase = {
+    id,
+    tool,
+    pattern,
+    decision,
+    priority,
+    createdAt,
+    ...(userModifiedAt != null ? { userModifiedAt } : {}),
+  };
+
+  // Determine the family and strip invalid fields
+  if (URL_TOOLS_SET.has(tool)) {
+    // URL rules must not carry executionTarget or scope.
+    if (raw.executionTarget !== undefined) {
+      normalized = true;
+    }
+    if (typeof raw.scope === "string" && raw.scope !== "everywhere") {
+      normalized = true;
+    }
+    // allowHighRisk is stripped (replaced by runtime determination).
+    if (raw.allowHighRisk !== undefined) {
+      normalized = true;
+    }
+    const rule: UrlTrustRule = { ...base, tool: tool as UrlTrustRule["tool"] };
+    return { rule, normalized };
+  }
+
+  if (MANAGED_SKILL_TOOLS_SET.has(tool)) {
+    // Managed skill rules must not carry executionTarget or scope.
+    if (raw.executionTarget !== undefined) {
+      normalized = true;
+    }
+    if (typeof raw.scope === "string" && raw.scope !== "everywhere") {
+      normalized = true;
+    }
+    // allowHighRisk is stripped (replaced by runtime determination).
+    if (raw.allowHighRisk !== undefined) {
+      normalized = true;
+    }
+    const rule: ManagedSkillTrustRule = {
+      ...base,
+      tool: tool as ManagedSkillTrustRule["tool"],
+    };
+    return { rule, normalized };
+  }
+
+  if (tool === SKILL_LOAD_TOOL) {
+    // Skill-load rules must not carry executionTarget or scope.
+    if (raw.executionTarget !== undefined) {
+      normalized = true;
+    }
+    if (typeof raw.scope === "string" && raw.scope !== "everywhere") {
+      normalized = true;
+    }
+    // allowHighRisk is stripped (replaced by runtime determination).
+    if (raw.allowHighRisk !== undefined) {
+      normalized = true;
+    }
+    const rule: SkillLoadTrustRule = { ...base, tool: SKILL_LOAD_TOOL };
+    return { rule, normalized };
+  }
+
+  if (SCOPED_TOOLS_SET.has(tool)) {
+    // Scoped rules include scope (defaulting to "everywhere") and preserve
+    // executionTarget.
+    const scope =
+      typeof raw.scope === "string"
+        ? raw.scope
+        : ((normalized = true), "everywhere");
+    const rule: ScopedTrustRule = {
+      ...base,
+      tool: tool as ScopedTrustRule["tool"],
+      scope,
+    };
+    if (
+      typeof raw.executionTarget === "string" &&
+      raw.executionTarget.length > 0
+    ) {
+      rule.executionTarget = raw.executionTarget;
+    } else if (raw.executionTarget !== undefined && raw.executionTarget !== "") {
+      normalized = true;
+    }
+    // allowHighRisk is stripped (replaced by runtime determination).
+    if (raw.allowHighRisk !== undefined) {
+      normalized = true;
+    }
+    return { rule, normalized };
+  }
+
+  // Generic (unknown) tool — strip scope (new tools that need scope must be
+  // added to SCOPED_TOOLS explicitly), preserve executionTarget for forward compat.
+  const rule: GenericTrustRule = { ...base };
+  if (
+    typeof raw.scope === "string" &&
+    raw.scope !== "" &&
+    raw.scope !== "everywhere"
+  ) {
+    normalized = true;
+  }
+  if (
+    typeof raw.executionTarget === "string" &&
+    raw.executionTarget.length > 0
+  ) {
+    rule.executionTarget = raw.executionTarget;
+  } else if (raw.executionTarget !== undefined && raw.executionTarget !== "") {
+    normalized = true;
+  }
+  // allowHighRisk is stripped (replaced by runtime determination).
+  if (raw.allowHighRisk !== undefined) {
+    normalized = true;
+  }
+  return { rule, normalized };
+}
+
+function isValidDecision(value: unknown): value is TrustDecision {
+  return value === "allow" || value === "deny" || value === "ask";
 }
 
 // ---------------------------------------------------------------------------
@@ -40,3 +386,51 @@ export interface TrustFileData {
   /** Set to true when the user explicitly accepts the starter approval bundle. */
   starterBundleAccepted?: boolean;
 }
+
+/**
+ * Result of parsing a raw trust file. Includes the parsed data and a flag
+ * indicating whether any rules were normalized.
+ */
+export interface ParsedTrustFileData {
+  data: TrustFileData;
+  /** True if any rules were normalized during parsing. */
+  normalized: boolean;
+}
+
+/**
+ * Parse and normalize a raw trust file object.
+ *
+ * Each rule in the `rules` array is run through `parseTrustRule` for
+ * family-aware normalization. The `normalized` flag in the result is true
+ * if *any* rule was modified, signaling the caller that a re-save is warranted.
+ */
+export function parseTrustFileData(
+  raw: Record<string, unknown>,
+): ParsedTrustFileData {
+  const version = typeof raw.version === "number" ? raw.version : 0;
+  const starterBundleAccepted =
+    raw.starterBundleAccepted === true ? true : undefined;
+  const rawRules = Array.isArray(raw.rules) ? raw.rules : [];
+
+  let anyNormalized = false;
+  const rules: TrustRule[] = [];
+
+  for (const rawRule of rawRules) {
+    if (rawRule == null || typeof rawRule !== "object" || Array.isArray(rawRule)) {
+      anyNormalized = true;
+      continue;
+    }
+    const { rule, normalized } = parseTrustRule(
+      rawRule as Record<string, unknown>,
+    );
+    if (normalized) anyNormalized = true;
+    rules.push(rule);
+  }
+
+  const data: TrustFileData = { version, rules };
+  if (starterBundleAccepted) {
+    data.starterBundleAccepted = true;
+  }
+
+  return { data, normalized: anyNormalized };
+}

package/node_modules/@vellumai/credential-storage/bun.lock

@@ -5,8 +5,8 @@
     "": {
       "name": "@vellumai/credential-storage",
       "devDependencies": {
-        "@types/bun": "^1.2.4",
-        "typescript": "^5.7.3",
+        "@types/bun": "1.3.10",
+        "typescript": "5.9.3",
       },
     },
   },

package/node_modules/@vellumai/credential-storage/package.json

@@ -12,7 +12,7 @@
     "test": "bun test src/"
   },
   "devDependencies": {
-    "@types/bun": "^1.2.4",
-    "typescript": "^5.7.3"
+    "@types/bun": "1.3.10",
+    "typescript": "5.9.3"
   }
 }

package/node_modules/@vellumai/credential-storage/src/oauth-runtime.ts

@@ -89,6 +89,8 @@ export interface RefreshBreakerState {
   consecutiveFailures: number;
   openedAt: number;
   cooldownMs: number;
+  /** Whether the breaker tripped due to a credential error (vs transient). */
+  isCredentialError: boolean;
 }
 
 /**
@@ -128,18 +130,34 @@ export class RefreshCircuitBreaker {
     this.breakers.delete(key);
   }
 
-  /** Record a failed refresh attempt, potentially opening the breaker. */
-  recordFailure(key: string): void {
+  /**
+   * Record a failed refresh attempt, potentially opening the breaker.
+   *
+   * @param isCredential - When true, the failure is a credential error
+   *   (revoked token, invalid client) that no amount of retrying will fix.
+   *   Only credential errors count toward opening the circuit breaker.
+   *   Transient errors (network timeouts, 5xx) are silently ignored here —
+   *   they do not trip the breaker and are not recorded. Upstream retry logic
+   *   in refreshOAuth2Token handles transient failures with exponential backoff.
+   */
+  recordFailure(key: string, isCredential = true): void {
+    if (!isCredential) {
+      // Transient failures should not trip the breaker. The retry logic in
+      // refreshOAuth2Token handles transient errors with its own backoff.
+      return;
+    }
     const state = this.breakers.get(key);
     if (!state) {
       this.breakers.set(key, {
         consecutiveFailures: 1,
         openedAt: 0,
         cooldownMs: INITIAL_COOLDOWN_MS,
+        isCredentialError: true,
       });
       return;
     }
     state.consecutiveFailures++;
+    state.isCredentialError = true;
     if (state.consecutiveFailures >= REFRESH_FAILURE_THRESHOLD) {
       // Only escalate cooldown on the exact failure that trips the breaker.
       // Concurrent in-flight failures that arrive after the threshold is

package/node_modules/@vellumai/egress-proxy/bun.lock

@@ -5,8 +5,8 @@
     "": {
       "name": "@vellumai/egress-proxy",
       "devDependencies": {
-        "@types/bun": "^1.2.4",
-        "typescript": "^5.7.3",
+        "@types/bun": "1.3.10",
+        "typescript": "5.9.3",
       },
     },
   },

package/node_modules/@vellumai/egress-proxy/package.json

@@ -12,7 +12,7 @@
     "test": "bun test src/"
   },
   "devDependencies": {
-    "@types/bun": "^1.2.4",
-    "typescript": "^5.7.3"
+    "@types/bun": "1.3.10",
+    "typescript": "5.9.3"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/credential-executor",
-  "version": "0.6.4",
+  "version": "0.6.5",
   "license": "MIT",
   "type": "module",
   "exports": {