@vellumai/assistant 0.3.18 → 0.3.20

package/src/runtime/routes/pairing-routes.ts

@@ -17,6 +17,8 @@ const log = getLogger('runtime-http');
 export interface PairingHandlerContext {
   pairingStore: PairingStore;
   bearerToken: string | undefined;
+  /** Feature-flag client token to include in pairing approval responses so iOS can PATCH flags. */
+  featureFlagToken: string | undefined;
   pairingBroadcast?: (msg: ServerMessage) => void;
 }
 
@@ -90,6 +92,7 @@ export async function handlePairingRequest(req: Request, ctx: PairingHandlerCont
         bearerToken: ctx.bearerToken,
         gatewayUrl: entry.gatewayUrl,
         localLanUrl: entry.localLanUrl,
+        ...(ctx.featureFlagToken ? { featureFlagToken: ctx.featureFlagToken } : {}),
       });
     }
 
@@ -138,6 +141,7 @@ export function handlePairingStatus(url: URL, ctx: PairingHandlerContext): Respo
       bearerToken: entry.bearerToken,
       gatewayUrl: entry.gatewayUrl,
       localLanUrl: entry.localLanUrl,
+      ...(ctx.featureFlagToken ? { featureFlagToken: ctx.featureFlagToken } : {}),
     });
   }
 

package/src/security/encrypted-store.ts

@@ -17,9 +17,9 @@ import {
   pbkdf2Sync,
   randomBytes,
 } from 'node:crypto';
-import { chmodSync,readFileSync, writeFileSync } from 'node:fs';
+import { chmodSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import { hostname, userInfo } from 'node:os';
-import { dirname,join } from 'node:path';
+import { dirname, join } from 'node:path';
 
 import { ensureDir,pathExists } from '../util/fs.js';
 import { getLogger } from '../util/logger.js';
@@ -94,24 +94,40 @@ function deriveKey(salt: Buffer): Buffer {
 
 /**
  * Read result: distinguishes "file missing" from "file corrupt/unreadable".
- * - `null`: file does not exist (safe to create)
+ * - `null`: file does not exist or was corrupt (backed up and removed)
  * - `StoreFile`: successfully parsed
- * - throws: file exists but cannot be parsed (corrupt/invalid)
+ * - throws: transient I/O error from readFileSync (EACCES, EMFILE, EIO, etc.)
  */
 function readStore(): StoreFile | null {
   const path = getStorePath();
   if (!pathExists(path)) return null;
 
+  // Read outside the parse try/catch so transient filesystem errors (EACCES,
+  // EMFILE, EIO) propagate to callers instead of triggering corruption recovery.
   const raw = readFileSync(path, 'utf-8');
-  const parsed = JSON.parse(raw);
-  if (parsed.version !== 1 || typeof parsed.salt !== 'string' || typeof parsed.entries !== 'object') {
-    throw new Error('Encrypted store has invalid format');
+
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed.version !== 1 || typeof parsed.salt !== 'string' || typeof parsed.entries !== 'object') {
+      throw new Error('Encrypted store has invalid format');
+    }
+    // Use null-prototype object for entries to prevent prototype pollution
+    const safeEntries: Record<string, EncryptedEntry> = Object.create(null);
+    Object.assign(safeEntries, parsed.entries);
+    parsed.entries = safeEntries;
+    return parsed as StoreFile;
+  } catch (err) {
+    // Corrupted or invalid store file — back it up and start fresh so the
+    // daemon doesn't crash on every credential access.
+    const backupPath = `${path}.corrupt.${Date.now()}`;
+    log.error({ err, backupPath }, 'Encrypted store is corrupt — backing up and resetting');
+    try {
+      renameSync(path, backupPath);
+    } catch (renameErr) {
+      log.warn({ err: renameErr }, 'Failed to back up corrupt store file');
+    }
+    return null;
   }
-  // Use null-prototype object for entries to prevent prototype pollution
-  const safeEntries: Record<string, EncryptedEntry> = Object.create(null);
-  Object.assign(safeEntries, parsed.entries);
-  parsed.entries = safeEntries;
-  return parsed as StoreFile;
 }
 
 function writeStore(store: StoreFile): void {
@@ -123,11 +139,9 @@ function writeStore(store: StoreFile): void {
 }
 
 function getOrCreateStore(): StoreFile {
-  const path = getStorePath();
-  if (pathExists(path)) {
-    // File exists — must be parseable, otherwise fail to prevent data loss
-    return readStore()!;
-  }
+  const existing = readStore();
+  if (existing) return existing;
+
   const salt = randomBytes(SALT_LENGTH);
   const entries: Record<string, EncryptedEntry> = Object.create(null);
   const store: StoreFile = {

package/src/security/keychain.ts

@@ -4,17 +4,22 @@
  * - macOS: uses the `security` CLI to interact with Keychain
  * - Linux: uses `secret-tool` (libsecret) for GNOME/KDE keyrings
  *
- * All operations are synchronous to match the config loader's sync API.
+ * Sync variants (getKey, setKey, deleteKey) match the config loader's sync API.
+ * Async variants (getKeyAsync, setKeyAsync, deleteKeyAsync) avoid blocking
+ * the event loop and should be preferred for non-startup code paths.
+ *
  * Callers should check `isKeychainAvailable()` before use and fall back
  * to encrypted-at-rest storage when the keychain is not accessible.
  */
 
-import { execFileSync } from 'node:child_process';
+import { execFile, execFileSync } from 'node:child_process';
+import { promisify } from 'node:util';
 
 import { getLogger } from '../util/logger.js';
 import { isLinux,isMacOS } from '../util/platform.js';
 
 const log = getLogger('keychain');
+const execFileAsync = promisify(execFile);
 
 const SERVICE_NAME = 'vellum-assistant';
 
@@ -67,6 +72,29 @@ export function isKeychainAvailable(): boolean {
   }
 }
 
+/** Async version of `isKeychainAvailable` — probes without blocking the event loop. */
+export async function isKeychainAvailableAsync(): Promise<boolean> {
+  try {
+    if (deps.isMacOS()) {
+      await execFileAsync('security', ['list-keychains'], {
+        timeout: 5000,
+      });
+      return true;
+    }
+
+    if (deps.isLinux()) {
+      await execFileAsync('which', ['secret-tool'], {
+        timeout: 5000,
+      });
+      return true;
+    }
+
+    return false;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Retrieve a secret from the OS keychain.
  * Returns `null` if the key doesn't exist.
@@ -251,3 +279,149 @@ function linuxDeleteKey(account: string): boolean {
     return false;
   }
 }
+
+// ---------------------------------------------------------------------------
+// Async variants — non-blocking alternatives to the sync functions above.
+// Preferred for non-startup code paths to avoid blocking the event loop.
+// ---------------------------------------------------------------------------
+
+/**
+ * Async version of `getKey` — retrieve a secret without blocking the event loop.
+ * Returns `null` if the key doesn't exist.
+ * Throws on runtime errors (keychain unavailable, locked, etc.).
+ */
+export async function getKeyAsync(account: string): Promise<string | null> {
+  if (deps.isMacOS()) return macosGetKeyAsync(account);
+  if (deps.isLinux()) return linuxGetKeyAsync(account);
+  return null;
+}
+
+/**
+ * Async version of `setKey` — store a secret without blocking the event loop.
+ * Returns true on success, false on failure.
+ */
+export async function setKeyAsync(account: string, value: string): Promise<boolean> {
+  try {
+    if (deps.isMacOS()) return await macosSetKeyAsync(account, value);
+    if (deps.isLinux()) return await linuxSetKeyAsync(account, value);
+    return false;
+  } catch (err) {
+    log.warn({ err, account }, 'Failed to write to keychain');
+    return false;
+  }
+}
+
+/**
+ * Async version of `deleteKey` — delete a secret without blocking the event loop.
+ * Returns true on success, false if not found or on failure.
+ */
+export async function deleteKeyAsync(account: string): Promise<boolean> {
+  try {
+    if (deps.isMacOS()) return await macosDeleteKeyAsync(account);
+    if (deps.isLinux()) return await linuxDeleteKeyAsync(account);
+    return false;
+  } catch (err) {
+    log.debug({ err, account }, 'Failed to delete from keychain');
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Async macOS Keychain
+// ---------------------------------------------------------------------------
+
+async function macosGetKeyAsync(account: string): Promise<string | null> {
+  try {
+    const { stdout } = await execFileAsync('security', [
+      'find-generic-password',
+      '-s', SERVICE_NAME,
+      '-a', account,
+      '-w',
+    ], { timeout: 5000 });
+    return stdout.replace(/\n$/, '') || null;
+  } catch (err: unknown) {
+    // Exit code 44 = item not found — return null.
+    if (err && typeof err === 'object' && 'code' in err && (err as { code: number }).code === 44) {
+      return null;
+    }
+    throw err;
+  }
+}
+
+async function macosSetKeyAsync(account: string, value: string): Promise<boolean> {
+  try {
+    await execFileAsync('security', [
+      'add-generic-password',
+      '-s', SERVICE_NAME,
+      '-a', account,
+      '-w', value,
+      '-U',
+    ], { timeout: 5000 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function macosDeleteKeyAsync(account: string): Promise<boolean> {
+  try {
+    await execFileAsync('security', [
+      'delete-generic-password',
+      '-s', SERVICE_NAME,
+      '-a', account,
+    ], { timeout: 5000 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Async Linux via `secret-tool`
+// ---------------------------------------------------------------------------
+
+async function linuxGetKeyAsync(account: string): Promise<string | null> {
+  try {
+    const { stdout } = await execFileAsync('secret-tool', [
+      'lookup',
+      'service', SERVICE_NAME,
+      'account', account,
+    ], { timeout: 5000 });
+    return stdout.replace(/\n$/, '') || null;
+  } catch (err: unknown) {
+    if (err && typeof err === 'object' && 'code' in err && (err as { code: number }).code === 1) {
+      const stderr = String((err as { stderr?: unknown }).stderr ?? '').trim();
+      if (stderr.length > 0) throw err;
+      return null;
+    }
+    throw err;
+  }
+}
+
+async function linuxSetKeyAsync(account: string, value: string): Promise<boolean> {
+  // secret-tool reads the secret from stdin
+  return new Promise<boolean>((resolve) => {
+    const child = execFile('secret-tool', [
+      'store',
+      '--label', `${SERVICE_NAME}: ${account}`,
+      'service', SERVICE_NAME,
+      'account', account,
+    ], { timeout: 5000 }, (err) => {
+      resolve(!err);
+    });
+    child.stdin?.end(value);
+  });
+}
+
+async function linuxDeleteKeyAsync(account: string): Promise<boolean> {
+  try {
+    await execFileAsync('secret-tool', [
+      'clear',
+      'service', SERVICE_NAME,
+      'account', account,
+    ], { timeout: 5000 });
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/security/secure-keys.ts

@@ -30,6 +30,19 @@ function getBackend(): Backend {
   return resolvedBackend;
 }
 
+async function getBackendAsync(): Promise<Backend> {
+  if (resolvedBackend !== undefined) return resolvedBackend;
+
+  if (await keychain.isKeychainAvailableAsync()) {
+    log.debug('Using OS keychain for secure key storage');
+    resolvedBackend = 'keychain';
+  } else {
+    log.debug('OS keychain unavailable, using encrypted file storage');
+    resolvedBackend = 'encrypted';
+  }
+  return resolvedBackend;
+}
+
 /**
  * Try a keychain operation; on failure, permanently downgrade to encrypted
  * backend and retry. This handles systems where the keychain CLI exists
@@ -167,6 +180,90 @@ export function isDowngradedFromKeychain(): boolean {
   return downgradedFromKeychain;
 }
 
+// ---------------------------------------------------------------------------
+// Async variants — non-blocking alternatives that avoid blocking the event
+// loop during keychain operations. Preferred for non-startup code paths.
+// ---------------------------------------------------------------------------
+
+/**
+ * Async version of `getSecureKey` — retrieve a secret without blocking.
+ */
+export async function getSecureKeyAsync(account: string): Promise<string | undefined> {
+  const backend = await getBackendAsync();
+  if (backend === 'keychain') {
+    try {
+      return (await keychain.getKeyAsync(account)) ?? undefined;
+    } catch {
+      log.warn('Keychain read failed at runtime, falling back to encrypted file storage');
+      resolvedBackend = 'encrypted';
+      downgradedFromKeychain = true;
+      return encryptedStore.getKey(account);
+    }
+  }
+  if (backend === 'encrypted') {
+    const value = encryptedStore.getKey(account);
+    if (value === undefined && downgradedFromKeychain) {
+      try {
+        return (await keychain.getKeyAsync(account)) ?? undefined;
+      } catch {
+        return undefined;
+      }
+    }
+    return value;
+  }
+  return undefined;
+}
+
+/**
+ * Async version of `setSecureKey` — store a secret without blocking.
+ */
+export async function setSecureKeyAsync(account: string, value: string): Promise<boolean> {
+  const backend = await getBackendAsync();
+  if (backend === 'encrypted') return encryptedStore.setKey(account, value);
+  if (backend !== 'keychain') return false;
+
+  const result = await keychain.setKeyAsync(account, value);
+  if (result === false) {
+    log.warn('Keychain operation failed at runtime, falling back to encrypted file storage');
+    resolvedBackend = 'encrypted';
+    downgradedFromKeychain = true;
+    return encryptedStore.setKey(account, value);
+  }
+  return result;
+}
+
+/**
+ * Async version of `deleteSecureKey` — delete a secret without blocking.
+ */
+export async function deleteSecureKeyAsync(account: string): Promise<boolean> {
+  const backend = await getBackendAsync();
+  if (backend === 'encrypted') {
+    const result = encryptedStore.deleteKey(account);
+    if (downgradedFromKeychain) {
+      await keychain.deleteKeyAsync(account); // best-effort
+    }
+    return result;
+  }
+  if (backend !== 'keychain') return false;
+
+  try {
+    if ((await keychain.getKeyAsync(account)) == null) {
+      return false;
+    }
+  } catch {
+    // fall through
+  }
+
+  const result = await keychain.deleteKeyAsync(account);
+  if (result === false) {
+    log.warn('Keychain operation failed at runtime, falling back to encrypted file storage');
+    resolvedBackend = 'encrypted';
+    downgradedFromKeychain = true;
+    return encryptedStore.deleteKey(account);
+  }
+  return result;
+}
+
 /** @internal Test-only: reset the cached backend so it's re-evaluated. */
 export function _resetBackend(): void {
   resolvedBackend = undefined;

package/src/security/tool-approval-digest.ts

@@ -0,0 +1,67 @@
+/**
+ * Canonical JSON serialization and deterministic SHA-256 hash for tool
+ * approval signatures.
+ *
+ * Producers (grant creators) and consumers (grant matchers) must use the
+ * same serialization to ensure digest equality.  The algorithm:
+ *   1. Sort object keys recursively (depth-first).
+ *   2. Convert to a canonical JSON string with no whitespace.
+ *   3. SHA-256 hash the UTF-8 bytes and return a lowercase hex digest.
+ */
+
+import { createHash } from 'node:crypto';
+
+// ---------------------------------------------------------------------------
+// Canonical JSON serialization
+// ---------------------------------------------------------------------------
+
+/**
+ * Recursively sort all object keys and return a deterministic JSON string.
+ *
+ * Handles nested objects, arrays (element order preserved), and primitive
+ * values.  `undefined` values inside objects are omitted (matching
+ * JSON.stringify semantics).  `null` is preserved.
+ */
+export function canonicalJsonSerialize(value: unknown): string {
+  return JSON.stringify(sortKeysDeep(value));
+}
+
+function sortKeysDeep(value: unknown): unknown {
+  if (value == null) return value;
+
+  if (Array.isArray(value)) {
+    return value.map(sortKeysDeep);
+  }
+
+  if (typeof value === 'object') {
+    const sorted: Record<string, unknown> = {};
+    const keys = Object.keys(value as Record<string, unknown>).sort();
+    for (const key of keys) {
+      sorted[key] = sortKeysDeep((value as Record<string, unknown>)[key]);
+    }
+    return sorted;
+  }
+
+  // Primitive — number, string, boolean
+  return value;
+}
+
+// ---------------------------------------------------------------------------
+// Digest computation
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute a deterministic SHA-256 hex digest over the canonical
+ * serialization of a tool invocation's name and input.
+ *
+ * The digest covers `{ toolName, input }` so that two invocations of the
+ * same tool with identical (deeply-equal) inputs always produce the same
+ * hash, regardless of key ordering in the original input object.
+ */
+export function computeToolApprovalDigest(
+  toolName: string,
+  input: Record<string, unknown>,
+): string {
+  const payload = canonicalJsonSerialize({ input, toolName });
+  return createHash('sha256').update(payload, 'utf8').digest('hex');
+}

package/src/skills/remote-skill-policy.ts

@@ -0,0 +1,131 @@
+export type RemoteSkillProvider = 'clawhub' | 'skillssh';
+
+export type SkillsShRisk = 'safe' | 'low' | 'medium' | 'high' | 'critical' | 'unknown';
+export type SkillsShRiskThreshold = Exclude<SkillsShRisk, 'unknown'>;
+
+export interface RemoteSkillPolicy {
+  /**
+   * When true, suspicious skills are excluded from installable lists
+   * and blocked from installation.
+   */
+  blockSuspicious: boolean;
+  /**
+   * When true, malware-blocked skills are excluded from installable lists
+   * and blocked from installation.
+   */
+  blockMalware: boolean;
+  /**
+   * Maximum allowed Skills.sh audit risk. Anything above this threshold is blocked.
+   */
+  maxSkillsShRisk: SkillsShRiskThreshold;
+}
+
+export interface ClawhubModerationState {
+  isSuspicious?: boolean;
+  isMalwareBlocked?: boolean;
+}
+
+export interface SkillsShAuditState {
+  risk?: SkillsShRisk | null;
+}
+
+interface RemoteSkillCandidateBase {
+  provider: RemoteSkillProvider;
+  slug: string;
+}
+
+export interface ClawhubRemoteSkillCandidate extends RemoteSkillCandidateBase {
+  provider: 'clawhub';
+  moderation?: ClawhubModerationState | null;
+}
+
+export interface SkillsShRemoteSkillCandidate extends RemoteSkillCandidateBase {
+  provider: 'skillssh';
+  audit?: SkillsShAuditState | null;
+}
+
+export type RemoteSkillCandidate =
+  | ClawhubRemoteSkillCandidate
+  | SkillsShRemoteSkillCandidate;
+
+export type RemoteSkillDenyReason =
+  | 'clawhub_suspicious'
+  | 'clawhub_malware_blocked'
+  | 'clawhub_moderation_missing'
+  | 'skillssh_risk_exceeds_threshold';
+
+export type RemoteSkillInstallDecision =
+  | { ok: true }
+  | { ok: false; reason: RemoteSkillDenyReason };
+
+export const DEFAULT_REMOTE_SKILL_POLICY: Readonly<RemoteSkillPolicy> = Object.freeze({
+  blockSuspicious: true,
+  blockMalware: true,
+  maxSkillsShRisk: 'medium',
+});
+
+const SKILLS_SH_RISK_RANK: Record<SkillsShRisk, number> = {
+  safe: 0,
+  low: 1,
+  medium: 2,
+  high: 3,
+  critical: 4,
+  // Fail closed when risk is unknown.
+  unknown: 5,
+};
+
+function normalizeSkillsShRisk(audit: SkillsShAuditState | null | undefined): SkillsShRisk {
+  const risk = audit?.risk;
+  if (risk == null) return 'unknown';
+  // Coerce unrecognized risk labels to 'unknown' so we fail closed.
+  if (!Object.hasOwn(SKILLS_SH_RISK_RANK, risk)) return 'unknown';
+  return risk;
+}
+
+function exceedsSkillsShRiskThreshold(
+  audit: SkillsShAuditState | null | undefined,
+  threshold: SkillsShRiskThreshold,
+): boolean {
+  const actualRisk = normalizeSkillsShRisk(audit);
+  return SKILLS_SH_RISK_RANK[actualRisk] > SKILLS_SH_RISK_RANK[threshold];
+}
+
+export function evaluateRemoteSkillInstall(
+  candidate: RemoteSkillCandidate,
+  policy: RemoteSkillPolicy = DEFAULT_REMOTE_SKILL_POLICY,
+): RemoteSkillInstallDecision {
+  if (candidate.provider === 'clawhub') {
+    // Fail closed: block Clawhub skills when moderation data is missing.
+    if (candidate.moderation == null) {
+      return { ok: false, reason: 'clawhub_moderation_missing' };
+    }
+
+    if (policy.blockMalware && candidate.moderation.isMalwareBlocked === true) {
+      return { ok: false, reason: 'clawhub_malware_blocked' };
+    }
+    if (policy.blockSuspicious && candidate.moderation.isSuspicious === true) {
+      return { ok: false, reason: 'clawhub_suspicious' };
+    }
+    return { ok: true };
+  }
+
+  if (exceedsSkillsShRiskThreshold(candidate.audit, policy.maxSkillsShRisk)) {
+    return { ok: false, reason: 'skillssh_risk_exceeds_threshold' };
+  }
+
+  return { ok: true };
+}
+
+export function isRemoteSkillInstallable(
+  candidate: RemoteSkillCandidate,
+  policy: RemoteSkillPolicy = DEFAULT_REMOTE_SKILL_POLICY,
+): boolean {
+  return evaluateRemoteSkillInstall(candidate, policy).ok;
+}
+
+export function filterInstallableRemoteSkills<T extends RemoteSkillCandidate>(
+  skills: T[],
+  policy: RemoteSkillPolicy = DEFAULT_REMOTE_SKILL_POLICY,
+): T[] {
+  return skills.filter((skill) => isRemoteSkillInstallable(skill, policy));
+}

package/src/tools/browser/browser-execution.ts

@@ -12,7 +12,7 @@ import {
 import type { ToolContext, ToolExecutionResult } from '../types.js';
 import { detectAuthChallenge, detectCaptchaChallenge, formatAuthChallenge } from './auth-detector.js';
 import type { PageResponse,RouteHandler } from './browser-manager.js';
-import { browserManager } from './browser-manager.js';
+import { browserManager, SCREENCAST_HEIGHT,SCREENCAST_WIDTH } from './browser-manager.js';
 import {
   ensureScreencast,
   getElementBounds,
@@ -770,7 +770,7 @@ export async function executeBrowserScroll(
       if (bounds) {
         // Convert screencast coords back to page coords for mouse.move
         const result = await page.evaluate(`(() => ({ vw: window.innerWidth, vh: window.innerHeight }))()`) as { vw: number; vh: number };
-        const scale = Math.min(1280 / result.vw, 960 / result.vh);
+        const scale = Math.min(SCREENCAST_WIDTH / result.vw, SCREENCAST_HEIGHT / result.vh);
         const pageX = (bounds.x + bounds.w / 2) / scale;
         const pageY = (bounds.y + bounds.h / 2) / scale;
         await page.mouse.move(pageX, pageY);