vellum 0.2.14 → 0.3.2

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

@@ -1,335 +0,0 @@
-/**
- * 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

@@ -1,52 +0,0 @@
-/**
- * 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

@@ -1,80 +0,0 @@
-/**
- * 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

@@ -1,122 +0,0 @@
-/**
- * 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;
-}