vellum 0.2.13 → 0.3.2

package/src/tools/contacts/contact-upsert.ts

@@ -1,64 +0,0 @@
-import type { ToolContext, ToolExecutionResult } from '../types.js';
-import { upsertContact } from '../../contacts/contact-store.js';
-
-function formatContact(c: ReturnType<typeof upsertContact>): string {
-  const lines = [
-    `Contact ${c.id}`,
-    `  Name: ${c.displayName}`,
-  ];
-  if (c.relationship) lines.push(`  Relationship: ${c.relationship}`);
-  lines.push(`  Importance: ${c.importance.toFixed(2)}`);
-  if (c.responseExpectation) lines.push(`  Response expectation: ${c.responseExpectation}`);
-  if (c.preferredTone) lines.push(`  Preferred tone: ${c.preferredTone}`);
-  if (c.interactionCount > 0) lines.push(`  Interactions: ${c.interactionCount}`);
-  if (c.channels.length > 0) {
-    lines.push('  Channels:');
-    for (const ch of c.channels) {
-      const primary = ch.isPrimary ? ' (primary)' : '';
-      lines.push(`    - ${ch.type}: ${ch.address}${primary}`);
-    }
-  }
-  return lines.join('\n');
-}
-
-export async function executeContactUpsert(
-  input: Record<string, unknown>,
-  _context: ToolContext,
-): Promise<ToolExecutionResult> {
-  const displayName = input.display_name as string | undefined;
-  if (!displayName || typeof displayName !== 'string' || displayName.trim().length === 0) {
-    return { content: 'Error: display_name is required and must be a non-empty string', isError: true };
-  }
-
-  const importance = input.importance as number | undefined;
-  if (importance !== undefined && (typeof importance !== 'number' || importance < 0 || importance > 1)) {
-    return { content: 'Error: importance must be a number between 0 and 1', isError: true };
-  }
-
-  const rawChannels = input.channels as Array<{ type: string; address: string; is_primary?: boolean }> | undefined;
-  const channels = rawChannels?.map((ch) => ({
-    type: ch.type,
-    address: ch.address,
-    isPrimary: ch.is_primary,
-  }));
-
-  try {
-    const contact = upsertContact({
-      id: input.id as string | undefined,
-      displayName: displayName.trim(),
-      relationship: input.relationship as string | undefined,
-      importance,
-      responseExpectation: input.response_expectation as string | undefined,
-      preferredTone: input.preferred_tone as string | undefined,
-      channels,
-    });
-
-    return {
-      content: `${contact.created ? 'Created' : 'Updated'} contact:\n${formatContact(contact)}`,
-      isError: false,
-    };
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    return { content: `Error: ${msg}`, isError: true };
-  }
-}

package/src/tools/credentials/account-registry.ts

@@ -1,127 +0,0 @@
-import { RiskLevel } from '../../permissions/types.js';
-import type { Tool, ToolContext, ToolExecutionResult } from '../types.js';
-import type { ToolDefinition } from '../../providers/types.js';
-import {
-  createAccount,
-  listAccounts,
-  getAccount,
-  updateAccount,
-} from '../../memory/account-store.js';
-
-class AccountManageTool implements Tool {
-  name = 'account_manage';
-  description = 'Create, list, get, or update account records';
-  category = 'credentials';
-  defaultRiskLevel = RiskLevel.Low;
-
-  getDefinition(): ToolDefinition {
-    return {
-      name: this.name,
-      description: this.description,
-      input_schema: {
-        type: 'object',
-        properties: {
-          action: {
-            type: 'string',
-            enum: ['create', 'list', 'get', 'update'],
-            description: 'CRUD operation',
-          },
-          id: {
-            type: 'string',
-            description: 'Account ID (for get/update)',
-          },
-          service: {
-            type: 'string',
-            description: 'Service name',
-          },
-          username: { type: 'string' },
-          email: { type: 'string' },
-          display_name: { type: 'string' },
-          status: {
-            type: 'string',
-            enum: ['active', 'pending_verification', 'suspended'],
-          },
-          credential_ref: {
-            type: 'string',
-            description: 'Service name linking to credential vault',
-          },
-          metadata: { type: 'object' },
-        },
-        required: ['action'],
-      },
-    };
-  }
-
-  async execute(input: Record<string, unknown>, _context: ToolContext): Promise<ToolExecutionResult> {
-    const action = input.action as string;
-
-    switch (action) {
-      case 'create': {
-        const service = input.service as string | undefined;
-        if (!service || typeof service !== 'string') {
-          return { content: 'Error: service is required for create action', isError: true };
-        }
-
-        const record = createAccount({
-          service,
-          username: input.username as string | undefined,
-          email: input.email as string | undefined,
-          displayName: input.display_name as string | undefined,
-          status: input.status as string | undefined,
-          credentialRef: input.credential_ref as string | undefined,
-          metadata: input.metadata as Record<string, unknown> | undefined,
-        });
-
-        return { content: JSON.stringify(record, null, 2), isError: false };
-      }
-
-      case 'list': {
-        const records = listAccounts({
-          service: input.service as string | undefined,
-          status: input.status as string | undefined,
-        });
-        return { content: JSON.stringify(records, null, 2), isError: false };
-      }
-
-      case 'get': {
-        const id = input.id as string | undefined;
-        if (!id || typeof id !== 'string') {
-          return { content: 'Error: id is required for get action', isError: true };
-        }
-
-        const record = getAccount(id);
-        if (!record) {
-          return { content: `Error: account not found: ${id}`, isError: true };
-        }
-        return { content: JSON.stringify(record, null, 2), isError: false };
-      }
-
-      case 'update': {
-        const id = input.id as string | undefined;
-        if (!id || typeof id !== 'string') {
-          return { content: 'Error: id is required for update action', isError: true };
-        }
-
-        const updated = updateAccount(id, {
-          service: input.service as string | undefined,
-          username: input.username as string | undefined,
-          email: input.email as string | undefined,
-          displayName: input.display_name as string | undefined,
-          status: input.status as string | undefined,
-          credentialRef: input.credential_ref as string | undefined,
-          metadata: input.metadata as Record<string, unknown> | undefined,
-        });
-
-        if (!updated) {
-          return { content: `Error: account not found: ${id}`, isError: true };
-        }
-        return { content: JSON.stringify(updated, null, 2), isError: false };
-      }
-
-      default:
-        return { content: `Error: unknown action "${action}"`, isError: true };
-    }
-  }
-}
-
-export const accountManageTool = new AccountManageTool();

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

@@ -1,107 +0,0 @@
-/** Opaque token representing a policy-checked authorization to use a credential. */
-export interface UsageToken {
-  tokenId: string;
-  credentialId: string;
-  service: string;
-  field: string;
-  toolName: string;
-  /** Timestamp (epoch ms) when this token was created. */
-  createdAt: number;
-  /** Whether this token has been consumed (single-use). */
-  consumed: boolean;
-}
-
-/** Request to authorize the use of a credential. */
-export interface AuthorizeRequest {
-  service: string;
-  field: string;
-  toolName: string;
-  /** Optional domain for domain-policy checking (used by browser tools). */
-  domain?: string;
-}
-
-/** Successful authorization result. */
-export interface AuthorizeSuccess {
-  authorized: true;
-  token: UsageToken;
-}
-
-/** Denied authorization result. */
-export interface AuthorizeDenied {
-  authorized: false;
-  reason: string;
-}
-
-export type AuthorizeResult = AuthorizeSuccess | AuthorizeDenied;
-
-/** Result of consuming a token. */
-export interface ConsumeResult {
-  success: boolean;
-  /** The storage key to read the secret from (only present on success). */
-  storageKey?: string;
-  /** The resolved value when a transient (one-time) credential was consumed. */
-  value?: string;
-  /** Error reason if consumption failed. */
-  reason?: string;
-}
-
-/** Request for the broker to fill a browser field without exposing plaintext. */
-export interface BrowserFillRequest {
-  service: string;
-  field: string;
-  toolName: string;
-  domain?: string;
-  /**
-   * Opaque fill callback — the broker calls this with the plaintext value internally.
-   * The caller provides the fill function but never receives the secret value.
-   */
-  fill: (value: string) => Promise<void>;
-}
-
-/** Result of a broker-mediated browser fill — contains only metadata, never plaintext. */
-export interface BrowserFillResult {
-  success: boolean;
-  reason?: string;
-}
-
-/** Request for the broker to use a credential server-side without exposing plaintext. */
-export interface ServerUseRequest<T> {
-  service: string;
-  field: string;
-  toolName: string;
-  /**
-   * Opaque callback — the broker calls this with the plaintext value internally.
-   * The caller provides the function but never receives the secret value directly.
-   */
-  execute: (value: string) => Promise<T>;
-}
-
-/** Result of a broker-mediated server-side credential use — contains the callback result, never plaintext. */
-export interface ServerUseResult<T> {
-  success: boolean;
-  result?: T;
-  reason?: string;
-}
-
-/** Request to look up a credential by ID for proxy injection (no secret exposed). */
-export interface ServerUseByIdRequest {
-  credentialId: string;
-  requestingTool: string;
-}
-
-/** Successful by-id lookup result — metadata + injection templates, never plaintext. */
-export interface ServerUseByIdSuccess {
-  success: true;
-  credentialId: string;
-  service: string;
-  field: string;
-  injectionTemplates: import('./policy-types.js').CredentialInjectionTemplate[];
-}
-
-/** Denied or not-found by-id lookup result. */
-export interface ServerUseByIdDenied {
-  success: false;
-  reason: string;
-}
-
-export type ServerUseByIdResult = ServerUseByIdSuccess | ServerUseByIdDenied;

package/src/tools/credentials/broker.ts

@@ -1,372 +0,0 @@
-import { v4 as uuid } from 'uuid';
-import type {
-  AuthorizeRequest,
-  AuthorizeResult,
-  BrowserFillRequest,
-  BrowserFillResult,
-  ConsumeResult,
-  ServerUseByIdRequest,
-  ServerUseByIdResult,
-  ServerUseRequest,
-  ServerUseResult,
-  UsageToken,
-} from './broker-types.js';
-import { getCredentialMetadata } from './metadata-store.js';
-import { resolveById } from './resolve.js';
-import { isToolAllowed } from './tool-policy.js';
-import { isDomainAllowed } from './domain-policy.js';
-import { getSecureKey } from '../../security/secure-keys.js';
-import { getLogger } from '../../util/logger.js';
-
-const log = getLogger('credential-broker');
-
-/**
- * Credential broker that issues single-use tokens for policy-checked credential access.
- *
- * The broker never exposes plaintext secret values. Instead, it:
- * 1. Checks that a credential exists and has metadata
- * 2. Issues a single-use token for the authorized usage
- * 3. On consumption, returns the storage key so the caller can read the secret internally
- *
- * Tool policy is enforced at authorize/fill time; domain policy is enforced at fill time.
- */
-export class CredentialBroker {
-  private tokens = new Map<string, UsageToken>();
-  /** Transient values for one-time send: consumed on first read, never persisted.
-   *  Values are wrapped in objects so post-await guards use reference identity
-   *  (not string value equality) to detect concurrent replacements. */
-  private transientValues = new Map<string, { value: string }>();
-
-  /**
-   * Inject a value for one-time use. The value is consumed on the next
-   * browserFill or consume call for this service/field pair, then discarded.
-   */
-  injectTransient(service: string, field: string, value: string): void {
-    const key = `credential:${service}:${field}`;
-    this.transientValues.set(key, { value });
-    log.info({ service, field }, 'Transient credential injected for one-time use');
-  }
-
-  /**
-   * Authorize the use of a credential for a specific tool and optional domain.
-   * Returns a single-use token on success, or a denial reason on failure.
-   */
-  authorize(request: AuthorizeRequest): AuthorizeResult {
-    const metadata = getCredentialMetadata(request.service, request.field);
-    if (!metadata) {
-      return {
-        authorized: false,
-        reason: `No credential found for ${request.service}/${request.field}`,
-      };
-    }
-
-    // Tool policy enforcement — deny if tool is not in the credential's allowed list
-    if (!isToolAllowed(request.toolName, metadata.allowedTools)) {
-      const tools = metadata.allowedTools ?? [];
-      return {
-        authorized: false,
-        reason: `Tool "${request.toolName}" is not allowed to use credential ${request.service}/${request.field}. ` +
-          (tools.length === 0
-            ? 'No tools are currently allowed — update the credential with allowed_tools via credential_store.'
-            : `Allowed tools: ${tools.join(', ')}.`),
-      };
-    }
-
-    const token: UsageToken = {
-      tokenId: uuid(),
-      credentialId: metadata.credentialId,
-      service: request.service,
-      field: request.field,
-      toolName: request.toolName,
-      createdAt: Date.now(),
-      consumed: false,
-    };
-
-    this.tokens.set(token.tokenId, token);
-    log.info({ tokenId: token.tokenId, service: request.service, field: request.field, tool: request.toolName },
-      'Usage token issued');
-
-    return { authorized: true, token: { ...token } };
-  }
-
-  /**
-   * Consume a previously issued token. Returns the storage key on success.
-   * Each token can only be consumed once.
-   */
-  consume(tokenId: string): ConsumeResult {
-    const token = this.tokens.get(tokenId);
-    if (!token) {
-      return { success: false, reason: 'Token not found or already revoked' };
-    }
-    if (token.consumed) {
-      return { success: false, reason: 'Token already consumed' };
-    }
-
-    token.consumed = true;
-    const storageKey = `credential:${token.service}:${token.field}`;
-    // Check for transient value first (one-time send) — consume and return the value
-    // directly since transient values are never persisted to secure storage.
-    const transient = this.transientValues.get(storageKey);
-    if (transient !== undefined) {
-      this.transientValues.delete(storageKey);
-      log.info({ tokenId, storageKey, transient: true }, 'Usage token consumed (transient)');
-      return { success: true, storageKey, value: transient.value };
-    }
-
-    log.info({ tokenId, storageKey }, 'Usage token consumed');
-    return { success: true, storageKey };
-  }
-
-  /**
-   * Revoke a token, removing it from the active set.
-   * Returns true if the token existed and was revoked.
-   */
-  revoke(tokenId: string): boolean {
-    const existed = this.tokens.delete(tokenId);
-    if (existed) {
-      log.info({ tokenId }, 'Usage token revoked');
-    }
-    return existed;
-  }
-
-  /** Revoke all tokens (e.g. on session teardown). */
-  revokeAll(): void {
-    const count = this.tokens.size;
-    this.tokens.clear();
-    if (count > 0) {
-      log.info({ count }, 'All usage tokens revoked');
-    }
-  }
-
-  /**
-   * Fill a browser field using a credential without exposing plaintext to the caller.
-   *
-   * The broker resolves the credential, reads the secret internally, and passes it
-   * to the provided fill callback. The return value contains only metadata — the
-   * plaintext never leaves this method's scope.
-   */
-  async browserFill(request: BrowserFillRequest): Promise<BrowserFillResult> {
-    const metadata = getCredentialMetadata(request.service, request.field);
-    if (!metadata) {
-      return {
-        success: false,
-        reason: `No credential found for ${request.service}/${request.field}`,
-      };
-    }
-
-    // Tool policy enforcement — deny if tool is not in the credential's allowed list
-    if (!isToolAllowed(request.toolName, metadata.allowedTools)) {
-      const tools = metadata.allowedTools ?? [];
-      return {
-        success: false,
-        reason: `Tool "${request.toolName}" is not allowed to use credential ${request.service}/${request.field}. ` +
-          (tools.length === 0
-            ? 'No tools are currently allowed — update the credential with allowed_tools via credential_store.'
-            : `Allowed tools: ${tools.join(', ')}.`),
-      };
-    }
-
-    // Domain policy enforcement — deny if the page domain is not in the credential's allowed list
-    const browserDomains = metadata.allowedDomains ?? [];
-    if (browserDomains.length > 0) {
-      if (!request.domain) {
-        return {
-          success: false,
-          reason: `Credential ${request.service}/${request.field} has a domain policy but no page domain was provided. ` +
-            `Allowed domains: ${browserDomains.join(', ')}.`,
-        };
-      }
-      if (!isDomainAllowed(request.domain, browserDomains)) {
-        return {
-          success: false,
-          reason: `Domain "${request.domain}" is not allowed for credential ${request.service}/${request.field}. ` +
-            `Allowed domains: ${browserDomains.join(', ')}.`,
-        };
-      }
-    }
-
-    const storageKey = `credential:${request.service}:${request.field}`;
-    // Check transient values first (one-time send), then fall back to keychain.
-    // Deletion is deferred until after a successful fill so the value survives
-    // transient failures (e.g. stale element, page navigation, Playwright timeout).
-    const transient = this.transientValues.get(storageKey);
-    const value = transient?.value ?? getSecureKey(storageKey);
-    if (!value) {
-      return {
-        success: false,
-        reason: `Credential metadata exists but no stored value for ${request.service}/${request.field}`,
-      };
-    }
-
-    try {
-      await request.fill(value);
-      // Only discard the transient value after a successful fill, and only if
-      // the map still holds the same reference — a concurrent injectTransient()
-      // call during the async fill could have replaced it with a new value.
-      if (transient !== undefined && this.transientValues.get(storageKey) === transient) {
-        this.transientValues.delete(storageKey);
-      }
-      log.info(
-        { service: request.service, field: request.field, tool: request.toolName },
-        'Browser fill completed',
-      );
-      return { success: true };
-    } catch (err) {
-      // Log the raw error for debugging but never return it — the callback
-      // error text may embed the credential value, leaking plaintext outside
-      // the broker's trust boundary.
-      log.error(
-        { err, service: request.service, field: request.field },
-        'Browser fill failed',
-      );
-      return { success: false, reason: 'Fill operation failed' };
-    }
-  }
-
-  /**
-   * Use a credential server-side without exposing plaintext to the caller.
-   *
-   * Like browserFill, the broker reads the secret internally and passes it
-   * to the provided callback. The return value contains only the callback's
-   * result — the plaintext never leaves this method's scope.
-   */
-  async serverUse<T>(request: ServerUseRequest<T>): Promise<ServerUseResult<T>> {
-    const metadata = getCredentialMetadata(request.service, request.field);
-    if (!metadata) {
-      return {
-        success: false,
-        reason: `No credential found for ${request.service}/${request.field}`,
-      };
-    }
-
-    if (!isToolAllowed(request.toolName, metadata.allowedTools)) {
-      const tools = metadata.allowedTools ?? [];
-      return {
-        success: false,
-        reason: `Tool "${request.toolName}" is not allowed to use credential ${request.service}/${request.field}. ` +
-          (tools.length === 0
-            ? 'No tools are currently allowed — update the credential with allowed_tools via credential_store.'
-            : `Allowed tools: ${tools.join(', ')}.`),
-      };
-    }
-
-    // Domain policy enforcement — credentials with domain restrictions are
-    // scoped to browser use on those domains and cannot be used server-side.
-    const serverDomains = metadata.allowedDomains ?? [];
-    if (serverDomains.length > 0) {
-      return {
-        success: false,
-        reason: `Credential ${request.service}/${request.field} has domain restrictions ` +
-          `(${serverDomains.join(', ')}) and cannot be used server-side. ` +
-          'Remove domain restrictions or use a separate credential without domain policy.',
-      };
-    }
-
-    const storageKey = `credential:${request.service}:${request.field}`;
-    const transient = this.transientValues.get(storageKey);
-    const value = transient?.value ?? getSecureKey(storageKey);
-    if (!value) {
-      return {
-        success: false,
-        reason: `Credential metadata exists but no stored value for ${request.service}/${request.field}`,
-      };
-    }
-
-    try {
-      const result = await request.execute(value);
-      if (transient !== undefined && this.transientValues.get(storageKey) === transient) {
-        this.transientValues.delete(storageKey);
-      }
-      log.info(
-        { service: request.service, field: request.field, tool: request.toolName },
-        'Server-side credential use completed',
-      );
-      return { success: true, result };
-    } catch (err) {
-      log.error(
-        { err, service: request.service, field: request.field },
-        'Server-side credential use failed',
-      );
-      return { success: false, reason: 'Credential use failed' };
-    }
-  }
-
-  /**
-   * Look up a credential by its opaque ID for proxy injection.
-   *
-   * Returns metadata and injection templates so the proxy knows how to
-   * inject the credential into outbound requests. The secret value is
-   * never included in the result — the proxy reads it separately via
-   * the secure key backend at injection time.
-   */
-  serverUseById(request: ServerUseByIdRequest): ServerUseByIdResult {
-    const resolved = resolveById(request.credentialId);
-    if (!resolved) {
-      return {
-        success: false,
-        reason: `No credential found for id "${request.credentialId}"`,
-      };
-    }
-
-    const { metadata } = resolved;
-
-    // Tool policy enforcement
-    if (!isToolAllowed(request.requestingTool, metadata.allowedTools)) {
-      const tools = metadata.allowedTools ?? [];
-      return {
-        success: false,
-        reason: `Tool "${request.requestingTool}" is not allowed to use credential ${metadata.service}/${metadata.field}. ` +
-          (tools.length === 0
-            ? 'No tools are currently allowed — update the credential with allowed_tools via credential_store.'
-            : `Allowed tools: ${tools.join(', ')}.`),
-      };
-    }
-
-    // Domain policy enforcement — credentials with domain restrictions are
-    // scoped to browser use on those domains and cannot be used server-side.
-    const domains = metadata.allowedDomains ?? [];
-    if (domains.length > 0) {
-      return {
-        success: false,
-        reason: `Credential ${metadata.service}/${metadata.field} has domain restrictions ` +
-          `(${domains.join(', ')}) and cannot be used server-side. ` +
-          'Remove domain restrictions or use a separate credential without domain policy.',
-      };
-    }
-
-    // Fail-closed: verify the secret value actually exists in secure storage.
-    // Without this, downstream proxy code would attempt unauthenticated requests.
-    const value = getSecureKey(resolved.storageKey);
-    if (!value) {
-      return {
-        success: false,
-        reason: `Credential metadata exists but no stored value for ${metadata.service}/${metadata.field}`,
-      };
-    }
-
-    log.info(
-      { credentialId: request.credentialId, service: metadata.service, field: metadata.field, tool: request.requestingTool },
-      'Server-side credential lookup by ID completed',
-    );
-
-    return {
-      success: true,
-      credentialId: resolved.credentialId,
-      service: resolved.service,
-      field: resolved.field,
-      injectionTemplates: resolved.injectionTemplates,
-    };
-  }
-
-  /** Return the number of active (non-consumed, non-revoked) tokens. */
-  get activeTokenCount(): number {
-    let count = 0;
-    for (const token of this.tokens.values()) {
-      if (!token.consumed) count++;
-    }
-    return count;
-  }
-}
-
-/** Shared singleton broker instance used by vault and browser tools. */
-export const credentialBroker = new CredentialBroker();