vellum 0.0.16 → 0.2.0

package/src/permissions/trust-store.ts

@@ -0,0 +1,584 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync, renameSync, chmodSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { v4 as uuid } from 'uuid';
+import { minimatch } from 'minimatch';
+import { getRootDir } from '../util/platform.js';
+import { getLogger } from '../util/logger.js';
+import { getDefaultRuleTemplates } from './defaults.js';
+import type { TrustRule, PolicyContext } from './types.js';
+
+const log = getLogger('trust-store');
+
+const TRUST_FILE_VERSION = 3;
+
+interface TrustFile {
+  version: number;
+  rules: TrustRule[];
+  /** Set to true when the user explicitly accepts the starter approval bundle. */
+  starterBundleAccepted?: boolean;
+}
+
+let cachedRules: TrustRule[] | null = null;
+let cachedStarterBundleAccepted: boolean | null = null;
+
+function getTrustPath(): string {
+  return join(getRootDir(), 'protected', 'trust.json');
+}
+
+/**
+ * Sort comparator: highest priority first. At the same priority, deny rules
+ * come before allow rules for safety (deny wins ties).
+ */
+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 };
+    return (order[a.decision] ?? 2) - (order[b.decision] ?? 2);
+  }
+  return 0;
+}
+
+/**
+ * Ensure default rules are always present in the rule set.
+ * Mutates the provided array and returns whether any rules were added.
+ */
+function backfillDefaults(rules: TrustRule[]): boolean {
+  let changed = false;
+  const existingIds = new Set(rules.map((r) => r.id));
+
+  // Migrate old default:deny-*-protected rules → default:ask-*-protected
+  const oldDefaultPrefix = 'default:deny-';
+  const newDefaultPrefix = 'default:ask-';
+  for (let i = rules.length - 1; i >= 0; i--) {
+    const rule = rules[i];
+    if (rule.id.startsWith(oldDefaultPrefix) && rule.id.endsWith('-protected')) {
+      const newId = newDefaultPrefix + rule.id.slice(oldDefaultPrefix.length);
+      rules.splice(i, 1);
+      existingIds.delete(rule.id);
+      // Don't add newId to existingIds — let the backfill loop re-add it
+      changed = true;
+      log.info({ oldId: rule.id, newId }, 'Migrated default deny rule to ask');
+    }
+  }
+
+  // Remove default rules that are no longer in the template set (e.g.
+  // computer_use_done/computer_use_respond were removed from the ask-rule list
+  // because they are terminal signal tools that don't need approval).
+  const templateIds = new Set(getDefaultRuleTemplates().map((t) => t.id));
+  for (let i = rules.length - 1; i >= 0; i--) {
+    const rule = rules[i];
+    if (rule.id.startsWith('default:') && !templateIds.has(rule.id)) {
+      rules.splice(i, 1);
+      existingIds.delete(rule.id);
+      changed = true;
+      log.info({ ruleId: rule.id }, 'Removed stale default trust rule');
+    }
+  }
+
+  // Migrate existing default rules whose priority, pattern, decision, or
+  // allowHighRisk has changed in the template (e.g. host_bash pattern changed
+  // from '*' to '**', host tool priorities changed from 1000 to 50).
+  for (const template of getDefaultRuleTemplates()) {
+    if (existingIds.has(template.id)) {
+      const rule = rules.find((r) => r.id === template.id);
+      if (rule && (
+        rule.priority !== template.priority
+        || rule.pattern !== template.pattern
+        || rule.decision !== template.decision
+        || rule.allowHighRisk !== template.allowHighRisk
+      )) {
+        log.info(
+          { ruleId: rule.id, oldPriority: rule.priority, newPriority: template.priority, oldPattern: rule.pattern, newPattern: template.pattern },
+          'Migrated default rule to updated template values',
+        );
+        rule.priority = template.priority;
+        rule.pattern = template.pattern;
+        rule.decision = template.decision;
+        if (template.allowHighRisk != null) {
+          rule.allowHighRisk = template.allowHighRisk;
+        } else {
+          delete rule.allowHighRisk;
+        }
+        changed = true;
+      }
+    }
+  }
+
+  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,
+        createdAt: Date.now(),
+      };
+      if (template.allowHighRisk != null) {
+        rule.allowHighRisk = template.allowHighRisk;
+      }
+      rules.push(rule);
+      changed = true;
+      log.info({ ruleId: template.id }, 'Backfilled default trust rule');
+    }
+  }
+  return changed;
+}
+
+/**
+ * Update persisted starter-bundle rules whose pattern matches a known legacy
+ * format (e.g. the old "tool:**" prefix was changed to standalone "**").
+ * Returns true when at least one rule was updated.
+ *
+ * Only rules with a recognised legacy pattern are migrated. If a user has
+ * intentionally customised a starter rule's pattern (e.g. narrowed it), it is
+ * left untouched.
+ */
+function migrateStarterRulePatterns(rules: TrustRule[]): boolean {
+  const templatesByID = new Map(getStarterBundleRules().map((t) => [t.id, t]));
+  let changed = false;
+  for (const rule of rules) {
+    const template = templatesByID.get(rule.id);
+    if (!template || rule.pattern === template.pattern) continue;
+    // Only migrate patterns that match a known legacy format.
+    // The "tool:**" prefix (e.g. "file_read:**") was the original pattern
+    // before it was changed to standalone "**".
+    if (!isLegacyStarterPattern(rule.pattern, rule.tool)) continue;
+    log.info(
+      { ruleId: rule.id, oldPattern: rule.pattern, newPattern: template.pattern },
+      'Migrated starter rule pattern to current template',
+    );
+    rule.pattern = template.pattern;
+    changed = true;
+  }
+  return changed;
+}
+
+/** Recognises legacy starter-rule patterns that should be auto-migrated. */
+function isLegacyStarterPattern(pattern: string, tool: string): boolean {
+  // Legacy format used "tool:**" prefixes, e.g. "file_read:**", "glob:**".
+  // Only match the exact legacy pattern for this specific tool to avoid
+  // silently resetting user-customised patterns.
+  return pattern === `${tool}:**`;
+}
+
+function loadFromDisk(): TrustRule[] {
+  const path = getTrustPath();
+  let rules: TrustRule[] = [];
+  let needsSave = false;
+
+  if (existsSync(path)) {
+    try {
+      const raw = readFileSync(path, 'utf-8');
+      const data = JSON.parse(raw) as TrustFile;
+
+      // Guard: ensure rules is an array (protects against hand-edited files)
+      const rawRules = Array.isArray(data.rules) ? data.rules : [];
+
+      // Restore persisted starter bundle flag
+      cachedStarterBundleAccepted = data.starterBundleAccepted === true;
+
+      if (data.version === 1) {
+        // Migration: v1 → v2. All existing rules are user-created → priority 100.
+        rules = rawRules.map((r) => ({
+          ...r,
+          priority: 100,
+        }));
+        needsSave = true;
+        log.info({ ruleCount: rules.length }, 'Migrated v1 trust rules to v2 (priority=100)');
+        // Fall through to v2 → v3 migration below
+      }
+
+      if (data.version === 2 || (data.version === 1 && needsSave)) {
+        // Migration: v2 → v3. Existing rules have no principal fields,
+        // which is correct — missing principal fields act as wildcards.
+        if (data.version === 2) {
+          rules = rawRules;
+        }
+        needsSave = true;
+        log.info({ ruleCount: rules.length }, 'Migrated v2 trust rules to v3 (principal fields)');
+      } else if (data.version === TRUST_FILE_VERSION) {
+        rules = rawRules;
+      } else if (data.version !== 1) {
+        log.warn({ version: data.version }, 'Unknown trust file version, applying defaults in-memory only');
+        // Apply default deny rules in-memory so the assistant is still
+        // protected, but do NOT persist — we must not overwrite a newer
+        // trust file format we don't understand.
+        const memRules: TrustRule[] = [];
+        backfillDefaults(memRules);
+        memRules.sort(ruleOrder);
+        return memRules;
+      }
+    } catch (err) {
+      log.error({ err }, 'Failed to load trust file');
+      // Fall through to backfill defaults even on parse errors
+    }
+  }
+
+  // Backfill default rules at their declared priority
+  if (backfillDefaults(rules)) {
+    needsSave = true;
+  }
+
+  // Migrate persisted starter rules whose pattern has drifted from the
+  // current template (e.g. old "tool:**" → "**").
+  if (migrateStarterRulePatterns(rules)) {
+    needsSave = true;
+  }
+
+  rules.sort(ruleOrder);
+
+  if (needsSave) {
+    try {
+      saveToDisk(rules);
+    } catch (err) {
+      log.warn({ err }, 'Failed to persist migrated trust rules (continuing with in-memory rules)');
+    }
+  }
+
+  return rules;
+}
+
+function saveToDisk(rules: TrustRule[]): void {
+  const path = getTrustPath();
+  const dir = dirname(path);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  const data: TrustFile = { version: TRUST_FILE_VERSION, rules };
+  if (cachedStarterBundleAccepted) {
+    data.starterBundleAccepted = true;
+  }
+  const tmpPath = path + '.tmp.' + process.pid;
+  writeFileSync(tmpPath, JSON.stringify(data, null, 2), { mode: 0o600 });
+  renameSync(tmpPath, path);
+  // Enforce owner-only permissions even if the file already existed with
+  // wider permissions. Matches the pattern used in encrypted-store.ts.
+  chmodSync(path, 0o600);
+}
+
+function getRules(): TrustRule[] {
+  if (cachedRules === null) {
+    cachedRules = loadFromDisk();
+  }
+  return cachedRules;
+}
+
+export function addRule(
+  tool: string,
+  pattern: string,
+  scope: string,
+  decision: 'allow' | 'deny' | 'ask' = 'allow',
+  priority: number = 100,
+  options?: {
+    allowHighRisk?: boolean;
+    principalKind?: string;
+    principalId?: string;
+    principalVersion?: string;
+    executionTarget?: string;
+  },
+): 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()];
+  const rule: TrustRule = {
+    id: uuid(),
+    tool,
+    pattern,
+    scope,
+    decision,
+    priority,
+    createdAt: Date.now(),
+  };
+  if (options?.allowHighRisk != null) {
+    rule.allowHighRisk = options.allowHighRisk;
+  }
+  if (options?.principalKind != null) {
+    rule.principalKind = options.principalKind;
+  }
+  if (options?.principalId != null) {
+    rule.principalId = options.principalId;
+  }
+  if (options?.principalVersion != null) {
+    rule.principalVersion = options.principalVersion;
+  }
+  if (options?.executionTarget != null) {
+    rule.executionTarget = options.executionTarget;
+  }
+  rules.push(rule);
+  rules.sort(ruleOrder);
+  cachedRules = rules;
+  saveToDisk(rules);
+  log.info({ rule }, 'Added trust rule');
+  return rule;
+}
+
+export function updateRule(
+  id: string,
+  updates: { tool?: string; pattern?: string; scope?: string; decision?: 'allow' | 'deny' | 'ask'; 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}`);
+
+  // Re-read from disk to avoid lost updates from concurrent modifications.
+  cachedRules = null;
+  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;
+  rules[index] = rule;
+  rules.sort(ruleOrder);
+  cachedRules = rules;
+  saveToDisk(rules);
+  log.info({ rule }, 'Updated trust rule');
+  return rule;
+}
+
+export function removeRule(id: string): boolean {
+  const defaultIds = new Set(getDefaultRuleTemplates().map((t) => t.id));
+  if (defaultIds.has(id)) throw new Error(`Cannot remove default trust rule: ${id}`);
+
+  // Re-read from disk to avoid lost updates from concurrent modifications.
+  cachedRules = null;
+  const rules = [...getRules()];
+  const index = rules.findIndex((r) => r.id === id);
+  if (index === -1) return false;
+  rules.splice(index, 1);
+  cachedRules = rules;
+  saveToDisk(rules);
+  log.info({ id }, 'Removed trust rule');
+  return true;
+}
+
+function matchesScope(ruleScope: string, workingDir: string): boolean {
+  if (ruleScope === 'everywhere') return true;
+  // Strip optional trailing wildcard, then enforce a directory-boundary match
+  // so that a rule for "/path/project" does NOT match "/path/project-evil".
+  const prefix = ruleScope.replace(/\*$/, '').replace(/\/+$/, '');
+  const dir = workingDir.replace(/\/+$/, '');
+  return dir === prefix || dir.startsWith(prefix + '/');
+}
+
+function findRuleByDecision(tool: string, command: string, scope: string, decision: 'allow' | 'deny' | 'ask'): TrustRule | null {
+  const rules = getRules();
+  for (const rule of rules) {
+    if (rule.tool !== tool) continue;
+    if (rule.decision !== decision) continue;
+    if (!minimatch(command, rule.pattern)) continue;
+    if (!matchesScope(rule.scope, scope)) continue;
+    return rule;
+  }
+  return null;
+}
+
+/**
+ * Check whether a rule's principal constraints match the given policy context.
+ *
+ * A missing field on the rule acts as a wildcard — it matches any value
+ * (or absence) in the context. When a rule specifies a principal field,
+ * the context must provide a matching value for the rule to apply.
+ */
+function matchesPrincipal(rule: TrustRule, ctx?: PolicyContext): boolean {
+  // If the rule has no principal constraints it matches everything (wildcard).
+  if (rule.principalKind == null && rule.principalId == null && rule.principalVersion == null) {
+    return true;
+  }
+
+  const principal = ctx?.principal;
+
+  // Rule specifies a principalKind — context must supply one that matches.
+  if (rule.principalKind != null) {
+    if (principal?.kind !== rule.principalKind) return false;
+  }
+
+  // Rule specifies a principalId — context must supply one that matches.
+  if (rule.principalId != null) {
+    if (principal?.id !== rule.principalId) return false;
+  }
+
+  // Rule specifies a principalVersion — context must supply one that matches.
+  // If the rule omits principalVersion, any version (or none) is accepted.
+  if (rule.principalVersion != null) {
+    if (principal?.version !== rule.principalVersion) return false;
+  }
+
+  return true;
+}
+
+/**
+ * Check whether a rule's executionTarget constraint matches the context.
+ *
+ * If the rule does not specify an executionTarget it matches any target
+ * (wildcard). If specified, it must match exactly.
+ */
+function matchesExecutionTarget(rule: TrustRule, ctx?: PolicyContext): boolean {
+  if (rule.executionTarget == null) return true;
+  return ctx?.executionTarget === rule.executionTarget;
+}
+
+/**
+ * Find the highest-priority rule that matches any of the command candidates.
+ * Rules are pre-sorted by priority descending, so the first match wins.
+ *
+ * When a `PolicyContext` is provided, rules that specify principal or
+ * executionTarget constraints are filtered accordingly. Rules without
+ * those constraints act as wildcards and match any context.
+ */
+export function findHighestPriorityRule(tool: string, commands: string[], scope: string, ctx?: PolicyContext): TrustRule | null {
+  // Check ephemeral (task-scoped) rules first — they take precedence over
+  // file-based rules at the same priority because they are evaluated earlier.
+  // The ruleOrder sort (highest priority first, deny wins ties) still applies
+  // across the combined set because ephemeral rules use a lower default
+  // priority (50) than user rules (100), so user deny rules still win.
+  const ephemeral = ctx?.ephemeralRules ?? [];
+  const fileRules = getRules();
+
+  // Concatenate and re-sort so priority ordering is respected across both sets.
+  const allRules = ephemeral.length > 0
+    ? [...ephemeral, ...fileRules].sort(ruleOrder)
+    : fileRules;
+
+  for (const rule of allRules) {
+    if (rule.tool !== tool) continue;
+    if (!matchesScope(rule.scope, scope)) continue;
+    if (!matchesPrincipal(rule, ctx)) continue;
+    if (!matchesExecutionTarget(rule, ctx)) continue;
+    for (const command of commands) {
+      if (minimatch(command, rule.pattern)) {
+        return rule;
+      }
+    }
+  }
+  return null;
+}
+
+export function findMatchingRule(tool: string, command: string, scope: string): TrustRule | null {
+  return findRuleByDecision(tool, command, scope, 'allow');
+}
+
+export function findDenyRule(tool: string, command: string, scope: string): TrustRule | null {
+  return findRuleByDecision(tool, command, scope, 'deny');
+}
+
+export function getAllRules(): TrustRule[] {
+  return [...getRules()];
+}
+
+export function clearAllRules(): void {
+  // Reset the starter bundle flag so the bundle can be re-accepted after clear.
+  cachedStarterBundleAccepted = false;
+  // Re-backfill default rules so protected directory stays guarded.
+  const rules: TrustRule[] = [];
+  backfillDefaults(rules);
+  rules.sort(ruleOrder);
+  cachedRules = rules;
+  saveToDisk(rules);
+  log.info('Cleared all user trust rules (default rules preserved)');
+}
+
+export function clearCache(): void {
+  cachedRules = null;
+  cachedStarterBundleAccepted = null;
+}
+
+// ─── Starter approval bundle ────────────────────────────────────────────────
+//
+// A curated set of low-risk tool rules that most users would approve
+// individually during normal use.  Accepting the bundle seeds them all at
+// once, reducing prompt noise in strict mode while keeping the action
+// explicitly opt-in.
+
+export interface StarterBundleRule {
+  id: string;
+  tool: string;
+  pattern: string;
+  scope: string;
+  decision: 'allow';
+  priority: number;
+}
+
+/**
+ * Returns the starter bundle rule definitions.  These cover read-only and
+ * information-gathering tools that never mutate the filesystem or execute
+ * arbitrary code.
+ */
+export function getStarterBundleRules(): StarterBundleRule[] {
+  return [
+    // Use standalone "**" globstar — minimatch only treats ** as globstar when
+    // it is its own path segment, so a "tool:**" prefix would collapse to
+    // single-star behavior and fail to match candidates containing "/".
+    // The tool field is already filtered by findHighestPriorityRule.
+    { id: 'starter:allow-file_read', tool: 'file_read', pattern: '**', scope: 'everywhere', decision: 'allow', priority: 90 },
+    { id: 'starter:allow-glob', tool: 'glob', pattern: '**', scope: 'everywhere', decision: 'allow', priority: 90 },
+    { id: 'starter:allow-grep', tool: 'grep', pattern: '**', scope: 'everywhere', decision: 'allow', priority: 90 },
+    { id: 'starter:allow-list_directory', tool: 'list_directory', pattern: '**', scope: 'everywhere', decision: 'allow', priority: 90 },
+    { id: 'starter:allow-web_search', tool: 'web_search', pattern: '**', scope: 'everywhere', decision: 'allow', priority: 90 },
+    { id: 'starter:allow-web_fetch', tool: 'web_fetch', pattern: '**', scope: 'everywhere', decision: 'allow', priority: 90 },
+  ];
+}
+
+/** Whether the user has previously accepted the starter bundle. */
+export function isStarterBundleAccepted(): boolean {
+  // Ensure rules are loaded (which also loads the flag from disk)
+  getRules();
+  return cachedStarterBundleAccepted === true;
+}
+
+export interface AcceptStarterBundleResult {
+  accepted: boolean;
+  rulesAdded: number;
+  alreadyAccepted: boolean;
+}
+
+/**
+ * Seed the trust store with the starter bundle rules.
+ *
+ * Idempotent: if the bundle was already accepted, no rules are added and
+ * `alreadyAccepted` is returned as true.  Rules whose IDs already exist
+ * (e.g. from a previous partial acceptance) are skipped individually.
+ */
+export function acceptStarterBundle(): AcceptStarterBundleResult {
+  // Re-read from disk to avoid lost updates.
+  // loadFromDisk() also runs migrateStarterRulePatterns() to fix any
+  // stale patterns (e.g. old "tool:**" → "**") before we get here.
+  cachedRules = null;
+  cachedStarterBundleAccepted = null;
+  const rules = [...getRules()];
+
+  if (cachedStarterBundleAccepted === true) {
+    return { accepted: true, rulesAdded: 0, alreadyAccepted: true };
+  }
+
+  const existingIds = new Set(rules.map((r) => r.id));
+  let added = 0;
+
+  for (const template of getStarterBundleRules()) {
+    if (existingIds.has(template.id)) continue;
+    rules.push({
+      id: template.id,
+      tool: template.tool,
+      pattern: template.pattern,
+      scope: template.scope,
+      decision: template.decision,
+      priority: template.priority,
+      createdAt: Date.now(),
+    });
+    added++;
+  }
+
+  cachedStarterBundleAccepted = true;
+  rules.sort(ruleOrder);
+  cachedRules = rules;
+  saveToDisk(rules);
+  log.info({ rulesAdded: added }, 'Starter approval bundle accepted');
+
+  return { accepted: true, rulesAdded: added, alreadyAccepted: false };
+}

package/src/permissions/types.ts

@@ -0,0 +1,62 @@
+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;
+  // v3 fields — optional for backward compatibility with v2 rules
+  principalKind?: string;
+  principalId?: string;
+  principalVersion?: string;
+  executionTarget?: string;
+  allowHighRisk?: boolean;
+}
+
+export type UserDecision = 'allow' | 'always_allow' | 'always_allow_high_risk' | 'deny' | 'always_deny';
+
+export interface PermissionCheckResult {
+  decision: 'allow' | 'deny' | 'prompt';
+  reason: string;
+  matchedRule?: TrustRule;
+}
+
+export interface AllowlistOption {
+  label: string;
+  description: string;
+  pattern: string;
+}
+
+export interface ScopeOption {
+  label: string;
+  scope: string;
+}
+
+// ── Principal + policy context types (PR 3) ──────────────────
+
+/** Distinguishes whether a tool is a built-in core tool, provided by a skill, or scoped to a one-shot task. */
+export type ToolPrincipalKind = 'core' | 'skill' | 'task';
+
+/** Identifies the security principal that owns a tool invocation. */
+export interface ToolPrincipal {
+  kind: ToolPrincipalKind;
+  /** Skill ID when kind is 'skill'; task ID when kind is 'task'. */
+  id?: string;
+  /** Content-hash of the skill source at the time of approval. */
+  version?: string;
+}
+
+/** Contextual information passed alongside a permission check for policy decisions. */
+export interface PolicyContext {
+  principal?: ToolPrincipal;
+  executionTarget?: string;
+  /** Ephemeral rules for task-scoped permissions — checked before persistent trust.json rules. */
+  ephemeralRules?: TrustRule[];
+}

package/src/playbooks/index.ts

@@ -0,0 +1,2 @@
+export { type Playbook, type PlaybookAutonomyLevel, parsePlaybookStatement } from './types.js';
+export { compilePlaybooks, type CompiledPlaybooks, type CompilePlaybooksOptions } from './playbook-compiler.js';