@vellumai/assistant 0.3.0

package/src/tools/credentials/metadata-store.ts

@@ -0,0 +1,335 @@
+/**
+ * Credential metadata store.
+ *
+ * Persists non-secret metadata about credentials (policy, timestamps, IDs)
+ * in a versioned JSON file under protected storage. Secret values remain
+ * in the secure key backend only.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync, renameSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { getDataDir } from '../../util/platform.js';
+import { randomUUID } from 'node:crypto';
+import type { CredentialInjectionTemplate } from './policy-types.js';
+
+export interface CredentialMetadata {
+  credentialId: string;
+  service: string;
+  field: string;
+  allowedTools: string[];
+  allowedDomains: string[];
+  usageDescription?: string;
+  expiresAt?: number;
+  grantedScopes?: string[];
+  accountInfo?: string;
+  /** OAuth2 token endpoint — enables autonomous token refresh without an IntegrationDefinition. */
+  oauth2TokenUrl?: string;
+  /** OAuth2 client ID — paired with oauth2TokenUrl for refresh. */
+  oauth2ClientId?: string;
+  /** OAuth2 client secret — for providers that require it (e.g. Slack). Stored in metadata for autonomous refresh. */
+  oauth2ClientSecret?: string;
+  /** Human-friendly name for this credential (e.g. "fal-primary"). */
+  alias?: string;
+  /** Templates describing how to inject this credential into proxied requests. */
+  injectionTemplates?: CredentialInjectionTemplate[];
+  createdAt: number;
+  updatedAt: number;
+}
+
+/** Current on-disk schema version. */
+const CURRENT_VERSION = 2;
+
+interface MetadataFile {
+  version: typeof CURRENT_VERSION;
+  credentials: CredentialMetadata[];
+}
+
+let overridePath: string | null = null;
+
+function getMetadataPath(): string {
+  if (overridePath) return overridePath;
+  return join(getDataDir(), 'credentials', 'metadata.json');
+}
+
+/**
+ * Returned when the on-disk file has a version we don't understand.
+ * Callers that mutate state must check for this to avoid overwriting
+ * data written by a newer version of the app.
+ */
+interface UnknownVersionResult {
+  readonly unknownVersion: true;
+}
+
+type LoadResult = MetadataFile | UnknownVersionResult;
+
+function isUnknownVersion(r: LoadResult): r is UnknownVersionResult {
+  return 'unknownVersion' in r;
+}
+
+/**
+ * Returns true if a value looks like a valid credential record (has required fields).
+ * Filters out corrupted or incomplete entries during migration.
+ */
+function isValidCredentialRecord(record: unknown): record is Record<string, unknown> {
+  if (typeof record !== 'object' || record === null) return false;
+  const r = record as Record<string, unknown>;
+  return (
+    typeof r.credentialId === 'string' &&
+    typeof r.service === 'string' &&
+    typeof r.field === 'string' &&
+    typeof r.createdAt === 'number' &&
+    typeof r.updatedAt === 'number'
+  );
+}
+
+/**
+ * Migrate a v1 record to v2 by backfilling new optional fields with defaults.
+ */
+function migrateRecordV1toV2(record: Record<string, unknown>): CredentialMetadata {
+  return {
+    credentialId: record.credentialId as string,
+    service: record.service as string,
+    field: record.field as string,
+    allowedTools: Array.isArray(record.allowedTools) ? (record.allowedTools as string[]) : [],
+    allowedDomains: Array.isArray(record.allowedDomains) ? (record.allowedDomains as string[]) : [],
+    usageDescription: typeof record.usageDescription === 'string' ? record.usageDescription : undefined,
+    expiresAt: typeof record.expiresAt === 'number' ? record.expiresAt : undefined,
+    grantedScopes: Array.isArray(record.grantedScopes) ? (record.grantedScopes as string[]) : undefined,
+    accountInfo: typeof record.accountInfo === 'string' ? record.accountInfo : undefined,
+    oauth2TokenUrl: typeof record.oauth2TokenUrl === 'string' ? record.oauth2TokenUrl : undefined,
+    oauth2ClientId: typeof record.oauth2ClientId === 'string' ? record.oauth2ClientId : undefined,
+    oauth2ClientSecret: typeof record.oauth2ClientSecret === 'string' ? record.oauth2ClientSecret : undefined,
+    alias: typeof record.alias === 'string' ? record.alias : undefined,
+    injectionTemplates: Array.isArray(record.injectionTemplates)
+      ? (record.injectionTemplates as CredentialInjectionTemplate[])
+      : undefined,
+    createdAt: record.createdAt as number,
+    updatedAt: record.updatedAt as number,
+  };
+}
+
+function loadFile(): LoadResult {
+  const path = getMetadataPath();
+  if (!existsSync(path)) {
+    return { version: CURRENT_VERSION, credentials: [] };
+  }
+  try {
+    const raw = readFileSync(path, 'utf-8');
+    const data = JSON.parse(raw);
+    if (typeof data !== 'object' || data === null) {
+      return { version: CURRENT_VERSION, credentials: [] };
+    }
+    const fileVersion = typeof data.version === 'number' ? data.version : 1;
+    if (fileVersion !== 1 && fileVersion !== 2) {
+      // Unrecognized version (future, fractional, negative, zero) — refuse to touch it
+      return { unknownVersion: true };
+    }
+    const rawCredentials: unknown[] = Array.isArray(data.credentials) ? data.credentials : [];
+    // Filter out malformed entries that lack required fields
+    const validRecords = rawCredentials.filter(isValidCredentialRecord);
+
+    if (fileVersion < CURRENT_VERSION) {
+      // Migrate from v1 to v2 and persist the upgrade so we don't re-migrate on every read
+      const credentials = validRecords.map(migrateRecordV1toV2);
+      const migrated: MetadataFile = { version: CURRENT_VERSION, credentials };
+      try { saveFile(migrated); } catch { /* persist failed — will retry on next write */ }
+      return migrated;
+    }
+
+    return { version: CURRENT_VERSION, credentials: validRecords as unknown as CredentialMetadata[] };
+  } catch {
+    // Corrupted / unparseable file — treat as empty to avoid data loss on next write
+    return { version: CURRENT_VERSION, credentials: [] };
+  }
+}
+
+function saveFile(data: MetadataFile): void {
+  const path = getMetadataPath();
+  const dir = dirname(path);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  const tmpPath = join(dir, `.tmp-${randomUUID()}`);
+  writeFileSync(tmpPath, JSON.stringify(data, null, 2), 'utf-8');
+  renameSync(tmpPath, path);
+}
+
+/**
+ * Throws if the metadata file has an unrecognized version.
+ * Call this before performing irreversible keychain operations
+ * so the operation fails cleanly before any side effects.
+ */
+export function assertMetadataWritable(): void {
+  const result = loadFile();
+  if (isUnknownVersion(result)) {
+    throw new Error('Credential metadata file has an unrecognized version; refusing to mutate to avoid data loss');
+  }
+}
+
+/**
+ * Create or update a credential metadata record.
+ * If a record with the same service+field exists, it is updated.
+ */
+export function upsertCredentialMetadata(
+  service: string,
+  field: string,
+  policy?: {
+    allowedTools?: string[];
+    allowedDomains?: string[];
+    usageDescription?: string;
+    /** Pass `null` to explicitly clear a previously-set expiry. */
+    expiresAt?: number | null;
+    grantedScopes?: string[];
+    /** Pass `null` to explicitly clear a previously-set account info. */
+    accountInfo?: string | null;
+    oauth2TokenUrl?: string;
+    oauth2ClientId?: string;
+    /** Pass `null` to explicitly clear a previously-set client secret. */
+    oauth2ClientSecret?: string | null;
+    /** Pass `null` to explicitly clear a previously-set alias. */
+    alias?: string | null;
+    /** Pass `null` to explicitly clear injection templates. */
+    injectionTemplates?: CredentialInjectionTemplate[] | null;
+  },
+): CredentialMetadata {
+  const result = loadFile();
+  if (isUnknownVersion(result)) {
+    throw new Error('Credential metadata file has an unrecognized version; refusing to mutate to avoid data loss');
+  }
+  const data = result;
+  const now = Date.now();
+
+  const existing = data.credentials.find(
+    (c) => c.service === service && c.field === field,
+  );
+
+  if (existing) {
+    if (policy?.allowedTools !== undefined) existing.allowedTools = policy.allowedTools;
+    if (policy?.allowedDomains !== undefined) existing.allowedDomains = policy.allowedDomains;
+    if (policy?.usageDescription !== undefined) existing.usageDescription = policy.usageDescription;
+    if (policy?.expiresAt !== undefined) {
+      if (policy.expiresAt === null) {
+        delete existing.expiresAt;
+      } else {
+        existing.expiresAt = policy.expiresAt;
+      }
+    }
+    if (policy?.grantedScopes !== undefined) existing.grantedScopes = policy.grantedScopes;
+    if (policy?.accountInfo !== undefined) {
+      if (policy.accountInfo === null) {
+        delete existing.accountInfo;
+      } else {
+        existing.accountInfo = policy.accountInfo;
+      }
+    }
+    if (policy?.oauth2TokenUrl !== undefined) existing.oauth2TokenUrl = policy.oauth2TokenUrl;
+    if (policy?.oauth2ClientId !== undefined) existing.oauth2ClientId = policy.oauth2ClientId;
+    if (policy?.oauth2ClientSecret !== undefined) {
+      if (policy.oauth2ClientSecret === null) {
+        delete existing.oauth2ClientSecret;
+      } else {
+        existing.oauth2ClientSecret = policy.oauth2ClientSecret;
+      }
+    }
+    if (policy?.alias !== undefined) {
+      if (policy.alias === null) {
+        delete existing.alias;
+      } else {
+        existing.alias = policy.alias;
+      }
+    }
+    if (policy?.injectionTemplates !== undefined) {
+      if (policy.injectionTemplates === null) {
+        delete existing.injectionTemplates;
+      } else {
+        existing.injectionTemplates = policy.injectionTemplates;
+      }
+    }
+    existing.updatedAt = now;
+    saveFile(data);
+    return existing;
+  }
+
+  const record: CredentialMetadata = {
+    credentialId: randomUUID(),
+    service,
+    field,
+    allowedTools: policy?.allowedTools ?? [],
+    allowedDomains: policy?.allowedDomains ?? [],
+    usageDescription: policy?.usageDescription,
+    expiresAt: policy?.expiresAt ?? undefined,
+    grantedScopes: policy?.grantedScopes,
+    accountInfo: policy?.accountInfo ?? undefined,
+    oauth2TokenUrl: policy?.oauth2TokenUrl,
+    oauth2ClientId: policy?.oauth2ClientId,
+    oauth2ClientSecret: policy?.oauth2ClientSecret ?? undefined,
+    alias: policy?.alias ?? undefined,
+    injectionTemplates: policy?.injectionTemplates ?? undefined,
+    createdAt: now,
+    updatedAt: now,
+  };
+
+  data.credentials.push(record);
+  saveFile(data);
+  return record;
+}
+
+/**
+ * Get metadata for a credential by service and field.
+ */
+export function getCredentialMetadata(
+  service: string,
+  field: string,
+): CredentialMetadata | undefined {
+  const result = loadFile();
+  if (isUnknownVersion(result)) return undefined;
+  return result.credentials.find(
+    (c) => c.service === service && c.field === field,
+  );
+}
+
+/**
+ * Get metadata for a credential by its opaque ID.
+ */
+export function getCredentialMetadataById(
+  credentialId: string,
+): CredentialMetadata | undefined {
+  const result = loadFile();
+  if (isUnknownVersion(result)) return undefined;
+  return result.credentials.find((c) => c.credentialId === credentialId);
+}
+
+/**
+ * List all credential metadata records.
+ */
+export function listCredentialMetadata(): CredentialMetadata[] {
+  const result = loadFile();
+  if (isUnknownVersion(result)) return [];
+  return result.credentials;
+}
+
+/**
+ * Delete metadata for a credential.
+ */
+export function deleteCredentialMetadata(
+  service: string,
+  field: string,
+): boolean {
+  const result = loadFile();
+  if (isUnknownVersion(result)) {
+    throw new Error('Credential metadata file has an unrecognized version; refusing to mutate to avoid data loss');
+  }
+  const data = result;
+  const idx = data.credentials.findIndex(
+    (c) => c.service === service && c.field === field,
+  );
+  if (idx === -1) return false;
+  data.credentials.splice(idx, 1);
+  saveFile(data);
+  return true;
+}
+
+/** @internal Test-only: override the metadata file path. */
+export function _setMetadataPath(path: string | null): void {
+  overridePath = path;
+}

package/src/tools/credentials/policy-types.ts

@@ -0,0 +1,52 @@
+/**
+ * Credential usage policy types.
+ *
+ * These types define the constraints placed on how a stored credential
+ * may be used. Policies are attached at credential creation time and
+ * enforced by the CredentialBroker before any secret operation.
+ */
+
+/** How a credential was originally captured. */
+export type CredentialCreationFlow = 'secure_prompt' | 'tool_store' | 'migration';
+
+/** Policy that governs how a credential may be used. */
+export interface CredentialPolicy {
+  /** Tools allowed to consume this credential (fail-closed if empty). */
+  allowedTools: string[];
+
+  /** Registrable domains where this credential may be used (fail-closed if empty). */
+  allowedDomains: string[];
+
+  /** Human-readable description of intended usage. */
+  usageDescription?: string;
+
+  /** How the credential was originally captured. */
+  createdByFlow?: CredentialCreationFlow;
+}
+
+/** How a credential value is injected into an outbound proxied request. */
+export type CredentialInjectionType = 'header' | 'query';
+
+/**
+ * Describes where and how to inject a credential into proxied requests
+ * matching a specific host pattern.
+ */
+export interface CredentialInjectionTemplate {
+  /** Glob pattern for matching request hosts (e.g. "*.fal.ai"). */
+  hostPattern: string;
+  /** Where the credential value is injected. */
+  injectionType: CredentialInjectionType;
+  /** Header name when injectionType is 'header' (e.g. "Authorization"). */
+  headerName?: string;
+  /** Prefix prepended to the secret value (e.g. "Key ", "Bearer "). */
+  valuePrefix?: string;
+  /** Query parameter name when injectionType is 'query'. */
+  queryParamName?: string;
+}
+
+/** Input fields for specifying policy when storing a credential. */
+export interface CredentialPolicyInput {
+  allowed_tools?: string[];
+  allowed_domains?: string[];
+  usage_description?: string;
+}

package/src/tools/credentials/policy-validate.ts

@@ -0,0 +1,80 @@
+/**
+ * Pure validation helpers for credential policies.
+ *
+ * These functions validate policy input without side effects.
+ * They are used during credential creation and update to ensure
+ * policy data is well-formed before persistence.
+ */
+
+import type { CredentialPolicy, CredentialPolicyInput } from './policy-types.js';
+
+export interface ValidationResult {
+  valid: boolean;
+  errors: string[];
+}
+
+/**
+ * Validate a credential policy input.
+ * Returns a result with `valid: true` if the input is well-formed,
+ * or `valid: false` with a list of error messages.
+ */
+export function validatePolicyInput(input: CredentialPolicyInput): ValidationResult {
+  const errors: string[] = [];
+
+  if (input.allowed_tools !== undefined) {
+    if (!Array.isArray(input.allowed_tools)) {
+      errors.push('allowed_tools must be an array of strings');
+    } else {
+      for (let i = 0; i < input.allowed_tools.length; i++) {
+        const tool = input.allowed_tools[i];
+        if (typeof tool !== 'string' || tool.trim().length === 0) {
+          errors.push(`allowed_tools[${i}] must be a non-empty string`);
+        }
+      }
+    }
+  }
+
+  if (input.allowed_domains !== undefined) {
+    if (!Array.isArray(input.allowed_domains)) {
+      errors.push('allowed_domains must be an array of strings');
+    } else {
+      for (let i = 0; i < input.allowed_domains.length; i++) {
+        const domain = input.allowed_domains[i];
+        if (typeof domain !== 'string' || domain.trim().length === 0) {
+          errors.push(`allowed_domains[${i}] must be a non-empty string`);
+        }
+      }
+    }
+  }
+
+  if (input.usage_description !== undefined) {
+    if (typeof input.usage_description !== 'string') {
+      errors.push('usage_description must be a string');
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Convert validated policy input into a CredentialPolicy.
+ * Applies strict defaults: empty allowed lists = deny all.
+ */
+export function toPolicyFromInput(input: CredentialPolicyInput): CredentialPolicy {
+  return {
+    allowedTools: input.allowed_tools ?? [],
+    allowedDomains: input.allowed_domains ?? [],
+    usageDescription: input.usage_description,
+  };
+}
+
+/**
+ * Create a strict default policy (deny all usage).
+ * Used when a credential is stored without explicit policy.
+ */
+export function createStrictDefaultPolicy(): CredentialPolicy {
+  return {
+    allowedTools: [],
+    allowedDomains: [],
+  };
+}

package/src/tools/credentials/resolve.ts

@@ -0,0 +1,122 @@
+/**
+ * Credential resolver — maps between opaque IDs, service/field pairs,
+ * and storage locators.
+ *
+ * This decouples external credential references from the underlying
+ * secure key naming convention.
+ */
+
+import {
+  getCredentialMetadata,
+  getCredentialMetadataById,
+  listCredentialMetadata,
+  type CredentialMetadata,
+} from './metadata-store.js';
+import type { CredentialInjectionTemplate } from './policy-types.js';
+import { matchHostPattern } from './host-pattern-match.js';
+
+export interface ResolvedCredential {
+  credentialId: string;
+  service: string;
+  field: string;
+  /** The key used in the secure key backend. */
+  storageKey: string;
+  /** Human-friendly alias, if set. */
+  alias?: string;
+  /** Injection templates for proxied requests. */
+  injectionTemplates: CredentialInjectionTemplate[];
+  metadata: CredentialMetadata;
+}
+
+function toResolved(metadata: CredentialMetadata): ResolvedCredential {
+  return {
+    credentialId: metadata.credentialId,
+    service: metadata.service,
+    field: metadata.field,
+    storageKey: `credential:${metadata.service}:${metadata.field}`,
+    alias: metadata.alias,
+    injectionTemplates: metadata.injectionTemplates ?? [],
+    metadata,
+  };
+}
+
+/**
+ * Resolve a credential by service and field.
+ * Returns the resolved credential or undefined if not found.
+ */
+export function resolveByServiceField(
+  service: string,
+  field: string,
+): ResolvedCredential | undefined {
+  const metadata = getCredentialMetadata(service, field);
+  if (!metadata) return undefined;
+  return toResolved(metadata);
+}
+
+/**
+ * Resolve a credential by its opaque ID.
+ * Returns the resolved credential or undefined if not found.
+ */
+export function resolveById(
+  credentialId: string,
+): ResolvedCredential | undefined {
+  const metadata = getCredentialMetadataById(credentialId);
+  if (!metadata) return undefined;
+  return toResolved(metadata);
+}
+
+/**
+ * Resolve a credential reference that may be either a UUID or a "service/field" string.
+ *
+ * Resolution order:
+ * 1. Try as UUID via resolveById
+ * 2. If not found, try parsing as "service/field" via resolveByServiceField
+ *
+ * Returns undefined for malformed refs (e.g. no slash, too many slashes, empty segments)
+ * and for refs that don't match any stored credential.
+ */
+export function resolveCredentialRef(
+  ref: string,
+): ResolvedCredential | undefined {
+  if (!ref || ref.trim().length === 0) return undefined;
+
+  // Try as UUID first
+  const byId = resolveById(ref);
+  if (byId) return byId;
+
+  // Try as service/field
+  const slashIndex = ref.indexOf('/');
+  if (slashIndex <= 0 || slashIndex >= ref.length - 1) return undefined;
+  // Reject refs with more than one slash (e.g. "fal/api/key")
+  if (ref.indexOf('/', slashIndex + 1) !== -1) return undefined;
+
+  const service = ref.slice(0, slashIndex);
+  const field = ref.slice(slashIndex + 1);
+  return resolveByServiceField(service, field);
+}
+
+/**
+ * Find all credentials whose injection templates match a given hostname.
+ * Returns resolved credentials with their `injectionTemplates` filtered
+ * to only the matching entries.
+ */
+export function resolveForDomain(
+  hostname: string,
+): ResolvedCredential[] {
+  const all = listCredentialMetadata();
+  const results: ResolvedCredential[] = [];
+
+  for (const meta of all) {
+    const templates = meta.injectionTemplates ?? [];
+    const matching = templates.filter((t) =>
+      matchHostPattern(hostname, t.hostPattern, { includeApexForWildcard: true }) !== 'none',
+    );
+    if (matching.length === 0) continue;
+    results.push({
+      ...toResolved(meta),
+      injectionTemplates: matching,
+    });
+  }
+
+  return results;
+}