@vellumai/assistant 0.6.3 → 0.6.5

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

@@ -0,0 +1,274 @@
+/**
+ * File risk classifier — path-based risk classification for file tools.
+ *
+ * Implements RiskClassifier<FileClassifierInput> for all six file tool types:
+ * file_read, file_write, file_edit, host_file_read, host_file_write, host_file_edit.
+ *
+ * Risk escalation paths:
+ * - file_read: Low by default, High if targeting the actor token signing key.
+ * - file_write / file_edit: Low by default, High if targeting skill source
+ *   code or the workspace hooks directory.
+ * - host_file_read: Medium (tool registry default; no special escalation).
+ * - host_file_write / host_file_edit: Medium by default, High if targeting
+ *   skill source code or the workspace hooks directory.
+ */
+
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+
+import { getConfig } from "../config/loader.js";
+import {
+  isSkillSourcePath,
+  normalizeDirPath,
+  normalizeFilePath,
+} from "../skills/path-classifier.js";
+import {
+  getDeprecatedDir,
+  getProtectedDir,
+  getWorkspaceHooksDir,
+} from "../util/platform.js";
+import type { RiskAssessment, RiskClassifier } from "./risk-types.js";
+import type { AllowlistOption } from "./types.js";
+
+// ── Input type ───────────────────────────────────────────────────────────────
+
+/** Input to the file risk classifier. */
+export interface FileClassifierInput {
+  toolName:
+    | "file_read"
+    | "file_write"
+    | "file_edit"
+    | "host_file_read"
+    | "host_file_write"
+    | "host_file_edit";
+  filePath: string;
+  workingDir: string;
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+/**
+ * Check whether a resolved absolute path targets the actor token signing key.
+ * Covers both the per-instance protected dir, the legacy global path, and
+ * a relative "deprecated/actor-token-signing-key" resolved against workingDir.
+ */
+function isActorTokenSigningKeyPath(
+  resolvedPath: string,
+  workingDir: string,
+): boolean {
+  const signingKeyPaths = Array.from(
+    new Set([
+      join(homedir(), ".vellum", "protected", "actor-token-signing-key"),
+      join(getProtectedDir(), "actor-token-signing-key"),
+      join(getDeprecatedDir(), "actor-token-signing-key"),
+      resolve(workingDir, "deprecated", "actor-token-signing-key"),
+    ]),
+  );
+  return signingKeyPaths.includes(resolvedPath);
+}
+
+/**
+ * Check whether a resolved absolute path falls inside the workspace hooks
+ * directory (or IS the hooks directory itself).
+ */
+function isHooksPath(resolvedPath: string): boolean {
+  const normalizedHooksDir = normalizeDirPath(getWorkspaceHooksDir());
+  const normalizedPath = normalizeFilePath(resolvedPath);
+  const hooksDirNoTrailingSlash = normalizedHooksDir.slice(0, -1);
+  return (
+    normalizedPath === hooksDirNoTrailingSlash ||
+    normalizedPath.startsWith(normalizedHooksDir)
+  );
+}
+
+// ── Allowlist option helpers ──────────────────────────────────────────────────
+
+const FILE_TOOL_DISPLAY_NAMES: Record<string, string> = {
+  file_read: "file reads",
+  file_write: "file writes",
+  file_edit: "file edits",
+  host_file_read: "host file reads",
+  host_file_write: "host file writes",
+  host_file_edit: "host file edits",
+};
+
+function friendlyBasename(filePath: string): string {
+  const parts = filePath.split("/");
+  return parts[parts.length - 1] || filePath;
+}
+
+/**
+ * Build allowlist options for a file tool invocation, mirroring the logic
+ * in checker.ts `fileAllowlistStrategy()`. Options go from most specific
+ * (exact file) to broadest (all operations of this tool type).
+ */
+function buildFileAllowlistOptions(
+  toolName: string,
+  filePath: string,
+): AllowlistOption[] {
+  const toolLabel = FILE_TOOL_DISPLAY_NAMES[toolName] ?? toolName;
+  const options: AllowlistOption[] = [];
+
+  // Exact file path
+  options.push({
+    label: filePath,
+    description: "This file only",
+    pattern: `${toolName}:${filePath}`,
+  });
+
+  // Ancestor directory wildcards — walk up from immediate parent, stop at home dir or /
+  const home = homedir();
+  let dir = dirname(filePath);
+  const maxLevels = 3;
+  let levels = 0;
+  while (dir && dir !== "/" && dir !== "." && levels < maxLevels) {
+    const dirName = friendlyBasename(dir);
+    options.push({
+      label: `${dir}/**`,
+      description: `Anything in ${dirName}/`,
+      pattern: `${toolName}:${dir}/**`,
+    });
+    if (dir === home) break;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+    levels++;
+  }
+
+  // All operations of this tool type
+  options.push({
+    label: `${toolName}:*`,
+    description: `All ${toolLabel}`,
+    pattern: `${toolName}:*`,
+  });
+
+  return options;
+}
+
+// ── Classifier ───────────────────────────────────────────────────────────────
+
+/**
+ * File risk classifier implementation.
+ *
+ * Classifies all six file tool types by risk level, with escalation paths
+ * for skill source code, workspace hooks, and the actor token signing key.
+ */
+export class FileRiskClassifier implements RiskClassifier<FileClassifierInput> {
+  async classify(input: FileClassifierInput): Promise<RiskAssessment> {
+    const { toolName, filePath, workingDir } = input;
+    const allowlistOptions = filePath
+      ? buildFileAllowlistOptions(toolName, filePath)
+      : [];
+
+    switch (toolName) {
+      case "file_read": {
+        if (filePath) {
+          const resolvedPath = resolve(workingDir, filePath);
+          if (isActorTokenSigningKeyPath(resolvedPath, workingDir)) {
+            return {
+              riskLevel: "high",
+              reason: "Reads actor token signing key",
+              scopeOptions: [],
+              matchType: "registry",
+              allowlistOptions,
+            };
+          }
+        }
+        return {
+          riskLevel: "low",
+          reason: "File read (default)",
+          scopeOptions: [],
+          matchType: "registry",
+          allowlistOptions,
+        };
+      }
+
+      case "file_write":
+      case "file_edit": {
+        if (filePath) {
+          const resolvedPath = resolve(workingDir, filePath);
+          if (
+            isSkillSourcePath(resolvedPath, getConfig().skills.load.extraDirs)
+          ) {
+            return {
+              riskLevel: "high",
+              reason: "Writes to skill source code",
+              scopeOptions: [],
+              matchType: "registry",
+              allowlistOptions,
+            };
+          }
+          if (isHooksPath(resolvedPath)) {
+            return {
+              riskLevel: "high",
+              reason: "Writes to hooks directory",
+              scopeOptions: [],
+              matchType: "registry",
+              allowlistOptions,
+            };
+          }
+        }
+        return {
+          riskLevel: "low",
+          reason: `File ${toolName === "file_write" ? "write" : "edit"} (default)`,
+          scopeOptions: [],
+          matchType: "registry",
+          allowlistOptions,
+        };
+      }
+
+      case "host_file_read": {
+        // host_file_read has no special escalation paths — the tool registry
+        // declares it as Medium risk, and classifyRiskFromRegistry falls through
+        // to getTool() which returns that default.
+        return {
+          riskLevel: "medium",
+          reason: "Host file read (default)",
+          scopeOptions: [],
+          matchType: "registry",
+          allowlistOptions,
+        };
+      }
+
+      case "host_file_write":
+      case "host_file_edit": {
+        if (filePath) {
+          // Host file tools resolve paths without workingDir — resolve(filePath)
+          // treats the path as absolute or relative to cwd.
+          const resolvedPath = resolve(filePath);
+          if (
+            isSkillSourcePath(resolvedPath, getConfig().skills.load.extraDirs)
+          ) {
+            return {
+              riskLevel: "high",
+              reason: "Writes to skill source code",
+              scopeOptions: [],
+              matchType: "registry",
+              allowlistOptions,
+            };
+          }
+          if (isHooksPath(resolvedPath)) {
+            return {
+              riskLevel: "high",
+              reason: "Writes to hooks directory",
+              scopeOptions: [],
+              matchType: "registry",
+              allowlistOptions,
+            };
+          }
+        }
+        // Fall through to tool registry default (Medium).
+        return {
+          riskLevel: "medium",
+          reason: `Host file ${toolName === "host_file_write" ? "write" : "edit"} (default)`,
+          scopeOptions: [],
+          matchType: "registry",
+          allowlistOptions,
+        };
+      }
+    }
+  }
+}
+
+/** Singleton classifier instance. */
+export const fileRiskClassifier = new FileRiskClassifier();

package/src/permissions/risk-types.ts

@@ -0,0 +1,205 @@
+/**
+ * Types for the data-driven command risk classifier.
+ *
+ * All types are JSON-serializable — no native RegExp, no function references.
+ * Regex patterns are stored as strings (use `String.raw` for ergonomics in TS).
+ * This constraint exists because the registry will eventually be persisted to a
+ * DB with per-user/per-org overrides that need to round-trip cleanly.
+ *
+ * @see /docs/bash-risk-classifier-design.md
+ */
+
+import { type AllowlistOption, RiskLevel } from "./types.js";
+
+// ── Risk levels ──────────────────────────────────────────────────────────────
+
+/**
+ * Risk level for a classified command or tool invocation.
+ *
+ * - `"low"`: Read-only, no side effects (auto-allow in most policies)
+ * - `"medium"`: Writes to filesystem, network access, state changes (confirm)
+ * - `"high"`: Destructive, privilege escalation, force ops, arbitrary code exec
+ * - `"unknown"`: Not in registry, unrecognized command or arg pattern
+ */
+export type Risk = "low" | "medium" | "high" | "unknown";
+
+/**
+ * Risk levels that can be assigned to commands in the registry.
+ * Excludes "unknown" — that's a classifier output, not a registry value.
+ */
+export type RegistryRisk = "low" | "medium" | "high";
+
+// ── Risk assessment output ───────────────────────────────────────────────────
+
+/** A scope option presented to the user when classifying an unknown command. */
+export interface ScopeOption {
+  /** Stored in DB if user saves (always regex internally). */
+  pattern: string;
+  /** Human-readable description shown in UI. */
+  label: string;
+}
+
+/**
+ * The output of a risk classifier. Tool-agnostic — every classifier
+ * (bash, file_write, web_fetch, etc.) produces this same shape.
+ */
+export interface RiskAssessment {
+  /** Computed risk level. */
+  riskLevel: Risk;
+  /** Human-readable explanation of why this risk level was assigned. */
+  reason: string;
+  /** Scope options for the "save this classification" UI, narrowest to broadest. */
+  scopeOptions: ScopeOption[];
+  /** How the risk was determined. */
+  matchType: "user_rule" | "registry" | "unknown";
+  /**
+   * Allowlist options for the permission prompt "always allow" scope ladder.
+   * Populated by classifiers that unify risk classification and scope option
+   * generation. When present, `generateAllowlistOptions()` returns these
+   * directly instead of calling the per-tool strategy function.
+   */
+  allowlistOptions?: AllowlistOption[];
+}
+
+// ── Classifier interface ─────────────────────────────────────────────────────
+
+/**
+ * Generic risk classifier interface. Each tool type (bash, file_write, etc.)
+ * implements this with a tool-specific input type.
+ */
+export interface RiskClassifier<TInput> {
+  classify(input: TInput): Promise<RiskAssessment>;
+}
+
+// ── Bash classifier input ────────────────────────────────────────────────────
+
+/** Input to the bash risk classifier. */
+export interface BashClassifierInput {
+  /** The raw command string. */
+  command: string;
+  /** Which tool is being invoked. */
+  toolName: "bash" | "host_bash";
+  /** Working directory (for path resolution in arg rules). */
+  workingDir?: string;
+}
+
+// ── Command registry types ───────────────────────────────────────────────────
+
+/**
+ * A single arg-level risk rule within a command spec.
+ *
+ * Evaluated per arg token. If `flags` is set, the rule only fires when the
+ * arg matches one of those flags. If `valuePattern` is set, the arg (or the
+ * flag's consumed value) must match the regex.
+ */
+export interface ArgRule {
+  /**
+   * Stable ID for DB references, partial overrides, and audit trails.
+   * Convention: `"command:descriptor"` (e.g. `"curl:upload-file"`, `"rm:recursive-force"`).
+   */
+  id: string;
+  /**
+   * Flag(s) that trigger this rule. Omit for positional/any-arg matching.
+   * Combined short flags are listed as literals (e.g. `"-rf"`, `"-fr"`).
+   */
+  flags?: string[];
+  /**
+   * Regex string matched against the arg value. Omit if flag presence alone
+   * triggers the rule. Stored as a string (not a native RegExp) for JSON
+   * serialization.
+   */
+  valuePattern?: string;
+  /** Risk level when this rule fires. */
+  risk: RegistryRisk;
+  /** Human-readable reason (shown in permission prompt). */
+  reason: string;
+}
+
+/**
+ * Risk specification for a single command (or subcommand).
+ *
+ * The registry is a `Record<string, CommandRiskSpec>` mapping program names
+ * to their specs. Subcommands nest recursively.
+ */
+export interface CommandRiskSpec {
+  /** Base risk when no arg rules match. */
+  baseRisk: RegistryRisk;
+  /**
+   * Subcommand-level overrides. Keys are subcommand names
+   * (e.g. `{ push: { baseRisk: "medium", ... } }` under `git`).
+   * Subcommands can nest further (e.g. `git stash drop`).
+   */
+  subcommands?: Record<string, CommandRiskSpec>;
+  /** Arg-level rules, evaluated per arg. First match per arg wins. */
+  argRules?: ArgRule[];
+  /**
+   * Is this a wrapper command? (sudo, env, nice, etc.)
+   * When true, the classifier unwraps to find the inner command and
+   * takes the max of the wrapper's baseRisk and the inner command's risk.
+   */
+  isWrapper?: boolean;
+  /**
+   * Flags that put a wrapper into a non-exec mode (e.g. command -v, env -0).
+   * When the first arg matches a non-exec flag, skip unwrapping and classify
+   * the wrapper standalone against its own arg rules.
+   */
+  nonExecFlags?: string[];
+  /**
+   * Does this command have non-standard syntax where intermediate scope
+   * options would be confusing? (find, xargs, awk, etc.)
+   * When true, the scope ladder only offers exact match and command-level wildcard.
+   */
+  complexSyntax?: boolean;
+  /** Human-readable reason for the base risk (shown when no arg rule matches). */
+  reason?: string;
+  /**
+   * Global flags that consume the next token as a value (e.g. git -C <path>).
+   * Used by resolveSubcommand to skip past flag-value pairs when locating the
+   * first positional arg (the subcommand name).
+   */
+  globalValueFlags?: string[];
+}
+
+// ── User rule types ──────────────────────────────────────────────────────────
+
+/**
+ * A user-created risk classification rule.
+ *
+ * Created via the scope ladder UI (from permission prompts) or manually
+ * in settings. Stored in the user's DB.
+ */
+export interface UserRule {
+  /** Auto-generated unique ID. */
+  id: string;
+  /** Regex pattern (converted from glob at creation time). */
+  pattern: string;
+  /** User-assigned risk level. */
+  risk: RegistryRisk;
+  /** Human-readable label (shown in settings UI). */
+  label: string;
+  /** ISO 8601 timestamp of when the rule was created. */
+  createdAt: string;
+  /** How the rule was created. */
+  source: "scope_ladder" | "manual";
+}
+
+// ── Risk → RiskLevel mapping ─────────────────────────────────────────────────
+
+/**
+ * Map a classifier `Risk` value to the permission system's `RiskLevel` enum.
+ *
+ * `"unknown"` maps to `RiskLevel.Medium` — matching the existing checker.ts
+ * behavior where unrecognized commands are treated as medium-risk.
+ */
+export function riskToRiskLevel(risk: Risk): RiskLevel {
+  switch (risk) {
+    case "low":
+      return RiskLevel.Low;
+    case "medium":
+      return RiskLevel.Medium;
+    case "high":
+      return RiskLevel.High;
+    case "unknown":
+      return RiskLevel.Medium;
+  }
+}

package/src/permissions/secret-prompter.ts

@@ -14,6 +14,8 @@ export type SecretDelivery = "store" | "transient_send";
 export interface SecretPromptResult {
   value: string | null;
   delivery: SecretDelivery;
+  /** When set, the prompt could not be delivered and the value is null due to a delivery failure (not user cancellation). */
+  error?: "unsupported_channel";
 }
 
 interface PendingSecretPrompt {
@@ -22,21 +24,48 @@ interface PendingSecretPrompt {
   timer: ReturnType<typeof setTimeout>;
 }
 
+export interface SecretPrompterChannelContext {
+  /** The channel the conversation was initiated from (e.g. "slack", "macos"). */
+  channel?: string;
+  /** Whether the channel supports rendering dynamic UI (secure prompt dialogs). */
+  supportsDynamicUi?: boolean;
+}
+
 export class SecretPrompter {
   private pending = new Map<string, PendingSecretPrompt>();
   private sendToClient: (msg: ServerMessage) => void;
+  private broadcastToAllClients?: (msg: ServerMessage) => void;
+  private channelContext?: SecretPrompterChannelContext;
 
-  constructor(sendToClient: (msg: ServerMessage) => void) {
+  constructor(
+    sendToClient: (msg: ServerMessage) => void,
+    broadcastToAllClients?: (msg: ServerMessage) => void,
+  ) {
     this.sendToClient = sendToClient;
+    this.broadcastToAllClients = broadcastToAllClients;
   }
 
   updateSender(sendToClient: (msg: ServerMessage) => void): void {
     this.sendToClient = sendToClient;
   }
 
+  updateBroadcast(broadcastToAllClients?: (msg: ServerMessage) => void): void {
+    this.broadcastToAllClients = broadcastToAllClients;
+  }
+
+  setChannelContext(ctx: SecretPrompterChannelContext | undefined): void {
+    this.channelContext = ctx;
+  }
+
   /**
    * Send a secret_request to the client and wait for the response.
    *
+   * When the conversation originates from a channel that cannot render secure
+   * prompts (e.g. Slack), the request is broadcast to all connected clients
+   * via the SSE hub so the desktop app can display it. If no broadcast path
+   * is available and the channel doesn't support dynamic UI, the method
+   * fails fast with an error result rather than hanging until timeout.
+   *
    * SECURITY: Logs only metadata (requestId, service, field) — never the
    * returned secret value. The timeout path also returns a null value
    * without logging anything sensitive.
@@ -52,6 +81,20 @@ export class SecretPrompter {
     allowedTools?: string[],
     allowedDomains?: string[],
   ): Promise<SecretPromptResult> {
+    // Determine whether the originating channel can render secure prompts.
+    const channelSupportsPrompt =
+      this.channelContext?.supportsDynamicUi !== false;
+
+    // If the channel cannot render the prompt and there's no broadcast path
+    // to reach a desktop client, fail fast instead of hanging for 5 minutes.
+    if (!channelSupportsPrompt && !this.broadcastToAllClients) {
+      log.warn(
+        { service, field, channel: this.channelContext?.channel },
+        "Secret prompt requested from a channel that cannot render it and no broadcast path is available",
+      );
+      return { value: null, delivery: "store", error: "unsupported_channel" };
+    }
+
     const requestId = uuid();
 
     return new Promise((resolve, reject) => {
@@ -79,7 +122,15 @@ export class SecretPrompter {
         allowedDomains,
         allowOneTimeSend: config.secretDetection.allowOneTimeSend,
       };
-      this.sendToClient(msg);
+
+      // Use broadcastToAllClients when the originating channel cannot render
+      // secure prompts — this routes the request to the SSE hub where a
+      // connected desktop client can pick it up.
+      if (!channelSupportsPrompt && this.broadcastToAllClients) {
+        this.broadcastToAllClients(msg);
+      } else {
+        this.sendToClient(msg);
+      }
     });
   }