vellum 0.0.16 → 0.2.0

package/src/security/secure-keys.ts

@@ -0,0 +1,180 @@
+/**
+ * Unified secure key storage — tries OS keychain first, falls back to
+ * encrypted-at-rest file storage.
+ *
+ * Provides the same get/set/delete/list interface used by both backends.
+ * Backend selection is cached after the first call for the process lifetime.
+ */
+
+import * as keychain from './keychain.js';
+import * as encryptedStore from './encrypted-store.js';
+import { getLogger } from '../util/logger.js';
+
+const log = getLogger('secure-keys');
+
+type Backend = 'keychain' | 'encrypted' | null;
+let resolvedBackend: Backend | undefined;
+/** True when backend was downgraded from keychain to encrypted at runtime. */
+let downgradedFromKeychain = false;
+
+function getBackend(): Backend {
+  if (resolvedBackend !== undefined) return resolvedBackend;
+
+  if (keychain.isKeychainAvailable()) {
+    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
+ * but is unusable at runtime (headless/locked sessions).
+ */
+function withKeychainFallback<T>(
+  keychainFn: () => T,
+  encryptedFn: () => T,
+  fallbackValue: T,
+): T {
+  const backend = getBackend();
+  if (backend === 'encrypted') return encryptedFn();
+  if (backend !== 'keychain') return fallbackValue;
+
+  const result = keychainFn();
+  // keychain.setKey/deleteKey return false on failure.
+  // We downgrade on failures (false) to switch to encrypted backend.
+  if (result === false) {
+    log.warn('Keychain operation failed at runtime, falling back to encrypted file storage');
+    resolvedBackend = 'encrypted';
+    downgradedFromKeychain = true;
+    return encryptedFn();
+  }
+  return result;
+}
+
+/**
+ * Retrieve a secret from secure storage.
+ * Returns `undefined` if the key doesn't exist or on error.
+ */
+export function getSecureKey(account: string): string | undefined {
+  const backend = getBackend();
+  if (backend === 'keychain') {
+    try {
+      return keychain.getKey(account) ?? undefined;
+    } catch {
+      // Keychain runtime error on read — downgrade to encrypted store
+      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);
+    // After a runtime downgrade, keys may still exist in the keychain.
+    // Try keychain read as fallback so pre-downgrade keys remain accessible.
+    if (value === undefined && downgradedFromKeychain) {
+      try {
+        return keychain.getKey(account) ?? undefined;
+      } catch {
+        return undefined;
+      }
+    }
+    return value;
+  }
+  return undefined;
+}
+
+/**
+ * Store a secret in secure storage.
+ * Returns `true` on success, `false` on failure.
+ */
+export function setSecureKey(account: string, value: string): boolean {
+  return withKeychainFallback(
+    () => keychain.setKey(account, value),
+    () => encryptedStore.setKey(account, value),
+    false,
+  );
+}
+
+/**
+ * Delete a secret from secure storage.
+ * Returns `true` on success, `false` if not found or on error.
+ */
+export function deleteSecureKey(account: string): boolean {
+  const backend = getBackend();
+  if (backend === 'encrypted') {
+    const result = encryptedStore.deleteKey(account);
+    // After a runtime downgrade, keys may still exist in the keychain.
+    // Attempt best-effort cleanup so stale credentials don't linger.
+    if (downgradedFromKeychain) {
+      keychain.deleteKey(account); // best-effort, ignore result
+    }
+    return result;
+  }
+  if (backend !== 'keychain') return false;
+
+  // keychain.deleteKey returns false for both "not found" and "runtime error".
+  // Check existence first so a missing key doesn't spuriously downgrade the
+  // backend — saveConfig routinely deletes keys for unset providers.
+  // getKey now returns null for "not found" and throws on runtime errors.
+  try {
+    if (keychain.getKey(account) === null) {
+      return false;
+    }
+  } catch {
+    // Keychain runtime error — fall through to withKeychainFallback which
+    // will handle the downgrade when deleteKey also fails.
+  }
+
+  return withKeychainFallback(
+    () => keychain.deleteKey(account),
+    () => encryptedStore.deleteKey(account),
+    false,
+  );
+}
+
+/**
+ * List all account names in secure storage.
+ * Only supported by the encrypted backend; keychain returns empty array.
+ * Throws if the store file exists but cannot be read (encrypted backend).
+ */
+export function listSecureKeys(): string[] {
+  const backend = getBackend();
+  if (backend === 'encrypted') return encryptedStore.listKeys();
+  // OS keychains don't provide a list API scoped to our service
+  return [];
+}
+
+/**
+ * Return the currently resolved backend type.
+ * Useful for feature-gating behaviour that only works on certain backends.
+ */
+export function getBackendType(): 'keychain' | 'encrypted' | null {
+  return getBackend();
+}
+
+/**
+ * Whether the backend was downgraded from keychain to encrypted at runtime.
+ * When true, credentials may still be readable from keychain via fallback
+ * even though the active backend is encrypted.
+ */
+export function isDowngradedFromKeychain(): boolean {
+  return downgradedFromKeychain;
+}
+
+/** @internal Test-only: reset the cached backend so it's re-evaluated. */
+export function _resetBackend(): void {
+  resolvedBackend = undefined;
+  downgradedFromKeychain = false;
+}
+
+/** @internal Test-only: force a specific backend. Pass `undefined` to reset. */
+export function _setBackend(backend: Backend | undefined): void {
+  resolvedBackend = backend;
+  downgradedFromKeychain = false;
+}

package/src/security/token-manager.ts

@@ -0,0 +1,141 @@
+/**
+ * Metadata-driven token manager for OAuth2 credentials.
+ *
+ * Reads refresh configuration (tokenUrl, clientId) from credential metadata
+ * rather than requiring an IntegrationDefinition, enabling autonomous token
+ * refresh for any OAuth2 service that stores its config in metadata.
+ */
+
+import { getSecureKey, setSecureKey } from './secure-keys.js';
+import { getCredentialMetadata, upsertCredentialMetadata } from '../tools/credentials/metadata-store.js';
+import { refreshOAuth2Token } from './oauth2.js';
+import { getLogger } from '../util/logger.js';
+
+const log = getLogger('token-manager');
+
+/** Buffer before expiry to trigger proactive refresh (5 minutes). */
+const EXPIRY_BUFFER_MS = 5 * 60 * 1000;
+
+export class TokenExpiredError extends Error {
+  constructor(public readonly service: string, message?: string) {
+    super(message ?? `Token expired for "${service}". Re-authorization required.`);
+    this.name = 'TokenExpiredError';
+  }
+}
+
+/**
+ * Check whether the access token for a service is expired or will expire
+ * within the buffer window, based on the `expiresAt` field in credential metadata.
+ */
+function isTokenExpired(service: string): boolean {
+  const meta = getCredentialMetadata(service, 'access_token');
+  if (!meta?.expiresAt) return false;
+  return Date.now() >= meta.expiresAt - EXPIRY_BUFFER_MS;
+}
+
+/**
+ * Attempt to refresh the OAuth2 access token for a service using the
+ * refresh token and OAuth2 config stored in credential metadata.
+ *
+ * Returns the new access token on success.
+ * Throws `TokenExpiredError` if refresh is not possible.
+ */
+async function doRefresh(service: string): Promise<string> {
+  const refreshToken = getSecureKey(`credential:${service}:refresh_token`);
+  if (!refreshToken) {
+    throw new TokenExpiredError(service, `No refresh token available for "${service}". Re-authorization required.`);
+  }
+
+  const meta = getCredentialMetadata(service, 'access_token');
+  const tokenUrl = meta?.oauth2TokenUrl;
+  const clientId = meta?.oauth2ClientId;
+
+  if (!tokenUrl || !clientId) {
+    // Legacy credentials created by the old integration flow don't store
+    // oauth2TokenUrl/oauth2ClientId in metadata. The client ID is user-specific
+    // (from their Google Cloud Console) and cannot be recovered, so the only
+    // path forward is re-authorization via the new oauth2_connect flow.
+    const isLegacy = service === 'integration:gmail' && !tokenUrl && !clientId;
+    const hint = isLegacy
+      ? ` This is a one-time migration: your old Gmail connection needs to be re-authorized. Ask me to "reconnect Gmail" to set it up again.`
+      : '';
+    throw new TokenExpiredError(
+      service,
+      `Missing OAuth2 refresh config for "${service}".${hint} Please reconnect via chat to re-authorize.`,
+    );
+  }
+
+  const clientSecret = meta?.oauth2ClientSecret as string | undefined;
+  const resolvedTokenUrl = tokenUrl;
+
+  log.info({ service }, 'Refreshing OAuth2 access token');
+
+  const result = await refreshOAuth2Token(resolvedTokenUrl, clientId, refreshToken, clientSecret);
+
+  if (!setSecureKey(`credential:${service}:access_token`, result.accessToken)) {
+    throw new Error(`Failed to store refreshed access token for "${service}"`);
+  }
+
+  if (result.refreshToken) {
+    if (!setSecureKey(`credential:${service}:refresh_token`, result.refreshToken)) {
+      throw new Error(`Failed to store refreshed refresh token for "${service}"`);
+    }
+  }
+
+  // Update metadata with new expiry.
+  // Use null to explicitly clear a stale expiresAt when the provider omits
+  // expires_in (or returns 0), so isTokenExpired won't keep forcing refreshes.
+  const expiresAt = result.expiresIn != null && result.expiresIn > 0
+    ? Date.now() + result.expiresIn * 1000
+    : null;
+
+  upsertCredentialMetadata(service, 'access_token', { expiresAt });
+
+  log.info({ service }, 'OAuth2 access token refreshed successfully');
+  return result.accessToken;
+}
+
+/**
+ * Execute a callback with a valid access token for the given service.
+ *
+ * Handles token expiration transparently:
+ * 1. Retrieves the stored access token (throws if none exists).
+ * 2. If the token is expired or near-expiry, refreshes it before calling the callback.
+ * 3. If the callback throws with a 401 status, attempts one refresh-and-retry cycle.
+ */
+export async function withValidToken<T>(
+  service: string,
+  callback: (token: string) => Promise<T>,
+): Promise<T> {
+  let token = getSecureKey(`credential:${service}:access_token`);
+  if (!token) {
+    const isGoogle = service === 'integration:gmail';
+    const googleHint = isGoogle
+      ? ' Do NOT fabricate credentials. Install and load the "google-oauth-setup" skill to set up OAuth credentials properly.'
+      : '';
+    throw new TokenExpiredError(service, `No access token found for "${service}". Authorization required.${googleHint}`);
+  }
+
+  // Proactively refresh if expired or about to expire.
+  if (isTokenExpired(service)) {
+    token = await doRefresh(service);
+  }
+
+  try {
+    return await callback(token);
+  } catch (err: unknown) {
+    if (is401Error(err)) {
+      token = await doRefresh(service);
+      return callback(token);
+    }
+    throw err;
+  }
+}
+
+function is401Error(err: unknown): boolean {
+  if (err && typeof err === 'object') {
+    if ('status' in err && (err as { status: number }).status === 401) return true;
+    if ('statusCode' in err && (err as { statusCode: number }).statusCode === 401) return true;
+  }
+  return false;
+}

package/src/services/published-app-updater.ts

@@ -0,0 +1,69 @@
+/**
+ * Background service that auto-redeploys published apps when their content changes.
+ */
+
+import { createHash } from 'node:crypto';
+import { getLogger } from '../util/logger.js';
+import { getActivePublishedPageByAppId, updatePublishedPage } from '../memory/published-pages-store.js';
+import { getApp } from '../memory/app-store.js';
+import { deployHtmlToVercel } from './vercel-deploy.js';
+import { credentialBroker } from '../tools/credentials/broker.js';
+
+const log = getLogger('published-app-updater');
+
+export async function updatePublishedAppDeployment(appId: string): Promise<void> {
+  try {
+    // 1. Check if this app has an active published deployment
+    const publishedPage = getActivePublishedPageByAppId(appId);
+    if (!publishedPage) return;
+
+    // 2. Load the app to get current HTML
+    const app = getApp(appId);
+    if (!app || !app.htmlDefinition) {
+      log.warn({ appId }, 'Published app not found or has no HTML');
+      return;
+    }
+
+    // 3. Hash the current HTML and check if it changed
+    const newHash = createHash('sha256').update(app.htmlDefinition).digest('hex');
+    if (newHash === publishedPage.htmlHash) return; // No change
+
+    // 4. Get Vercel token — don't prompt, just skip if unavailable
+    const slug = publishedPage.projectSlug ?? `vellum-app-${appId}`;
+
+    const useResult = await credentialBroker.serverUse({
+      service: 'vercel',
+      field: 'api_token',
+      toolName: 'publish_page',
+      execute: async (token) => {
+        // 5. Deploy updated HTML using the same project slug
+        const result = await deployHtmlToVercel({
+          html: app.htmlDefinition,
+          name: slug,
+          token,
+        });
+
+        // 6. Update the published page record
+        updatePublishedPage(publishedPage.id, {
+          deploymentId: result.deploymentId,
+          publicUrl: result.url,
+          htmlHash: newHash,
+          publishedAt: Date.now(),
+        });
+
+        log.info(
+          { appId, deploymentId: result.deploymentId, url: result.url },
+          'Auto-updated published app deployment',
+        );
+
+        return result;
+      },
+    });
+
+    if (!useResult.success) {
+      log.warn({ appId, reason: useResult.reason }, 'Could not auto-update published app — no Vercel credential available');
+    }
+  } catch (err) {
+    log.error({ err, appId }, 'Failed to auto-update published app deployment');
+  }
+}

package/src/services/vercel-deploy.ts

@@ -0,0 +1,73 @@
+/**
+ * Thin wrapper around the Vercel REST API for deploying static HTML pages.
+ */
+
+export async function deployHtmlToVercel(opts: {
+  html: string;
+  name: string;
+  token: string;
+}): Promise<{ url: string; deploymentId: string }> {
+  const slug = opts.name
+    .toLowerCase()
+    .replace(/[^a-z0-9-]/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '');
+
+  const body = {
+    name: slug,
+    files: [
+      {
+        file: 'index.html',
+        data: Buffer.from(opts.html).toString('base64'),
+        encoding: 'base64',
+      },
+    ],
+    projectSettings: { framework: null },
+    target: 'production',
+  };
+
+  const response = await fetch('https://api.vercel.com/v13/deployments', {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${opts.token}`,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify(body),
+  });
+
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`Vercel deploy failed (${response.status}): ${text}`);
+  }
+
+  const data = (await response.json()) as { url: string; id: string };
+
+  let publicUrl = data.url;
+  if (!publicUrl.startsWith('https://')) {
+    publicUrl = `https://${publicUrl}`;
+  }
+
+  return { url: publicUrl, deploymentId: data.id };
+}
+
+export async function deleteVercelDeployment(
+  deploymentId: string,
+  token: string,
+): Promise<void> {
+  const response = await fetch(
+    `https://api.vercel.com/v13/deployments/${deploymentId}`,
+    {
+      method: 'DELETE',
+      headers: {
+        Authorization: `Bearer ${token}`,
+      },
+    },
+  );
+
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(
+      `Vercel delete deployment failed (${response.status}): ${text}`,
+    );
+  }
+}

package/src/skills/active-skill-tools.ts

@@ -0,0 +1,81 @@
+import type { Message } from '../providers/types.js';
+
+/** Matches both old (`<loaded_skill id="..." />`) and new versioned
+ *  (`<loaded_skill id="..." version="v1:hex" />`) marker formats.
+ *  Group 1 = skill ID, group 2 = version string (optional). */
+const LOADED_SKILL_RE =
+  /<loaded_skill\s+id="([^"]+)"(?:\s+version="([^"]+)")?\s*\/>/g;
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export interface ActiveSkillEntry {
+  id: string;
+  /** Present only when the marker includes a `version` attribute. */
+  version?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Scans conversation history for `<loaded_skill>` markers and returns an
+ * ordered, deduplicated list of active skill entries (ID + optional version).
+ *
+ * Supports two marker formats:
+ *   - Legacy:     `<loaded_skill id="skill-id" />`
+ *   - Versioned:  `<loaded_skill id="skill-id" version="v1:hexhash" />`
+ *
+ * Only `tool_result` blocks whose corresponding `tool_use` has
+ * `name === 'skill_load'` are considered.  This prevents user messages or
+ * arbitrary tool outputs from injecting fake skill activations.
+ */
+export function deriveActiveSkills(messages: Message[]): ActiveSkillEntry[] {
+  // First pass: collect tool_use IDs that belong to skill_load calls.
+  const skillLoadUseIds = new Set<string>();
+  for (const msg of messages) {
+    for (const block of msg.content) {
+      if (block.type === 'tool_use' && block.name === 'skill_load') {
+        skillLoadUseIds.add(block.id);
+      }
+    }
+  }
+
+  // Second pass: parse markers only from matching tool_result blocks.
+  const seen = new Set<string>();
+  const entries: ActiveSkillEntry[] = [];
+
+  for (const msg of messages) {
+    for (const block of msg.content) {
+      if (block.type !== 'tool_result') continue;
+      if (!skillLoadUseIds.has(block.tool_use_id)) continue;
+
+      const text = block.content;
+      if (!text) continue;
+
+      for (const match of text.matchAll(LOADED_SKILL_RE)) {
+        const id = match[1];
+        if (!seen.has(id)) {
+          seen.add(id);
+          const entry: ActiveSkillEntry = { id };
+          if (match[2]) {
+            entry.version = match[2];
+          }
+          entries.push(entry);
+        }
+      }
+    }
+  }
+
+  return entries;
+}
+
+/**
+ * Convenience wrapper that returns only the skill IDs (no version info).
+ * Kept for backward compatibility with callers that only need IDs.
+ */
+export function deriveActiveSkillIds(messages: Message[]): string[] {
+  return deriveActiveSkills(messages).map((e) => e.id);
+}