@vellumai/assistant 0.3.0

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

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

@@ -0,0 +1,372 @@
+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();

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

@@ -0,0 +1,51 @@
+/**
+ * Domain policy matcher for credential usage enforcement.
+ *
+ * Uses registrable-domain semantics: a credential allowed for "example.com"
+ * can be used on "login.example.com" or "app.example.com", but not on
+ * "notexample.com" or "example.co.uk".
+ */
+
+import { normalizeDomain } from '../network/domain-normalize.js';
+
+/**
+ * Check whether a request host is allowed by the credential's domain policy.
+ *
+ * @param requestHost - The hostname or URL of the current request/page
+ * @param allowedDomains - The credential's allowed domain list
+ * @returns true if the request host matches an allowed domain
+ *
+ * Matching rules:
+ * 1. Exact hostname match (case-insensitive)
+ * 2. Registrable-domain match with subdomain allowance
+ * 3. Deny if requestHost is missing, invalid, IP, or localhost
+ * 4. Deny if allowedDomains is empty or undefined (fail-closed)
+ */
+export function isDomainAllowed(requestHost: string, allowedDomains: string[]): boolean {
+  if (!allowedDomains || allowedDomains.length === 0) return false;
+
+  const requestInfo = normalizeDomain(requestHost);
+  if (!requestInfo) return false;
+
+  for (const allowed of allowedDomains) {
+    const allowedInfo = normalizeDomain(allowed);
+    if (!allowedInfo) continue;
+
+    // Exact hostname match
+    if (requestInfo.hostname === allowedInfo.hostname) return true;
+
+    // Registrable-domain match: request's registrable domain must equal
+    // the allowed entry's registrable domain, and the allowed entry
+    // must itself be a registrable domain (not a subdomain).
+    if (
+      requestInfo.registrableDomain &&
+      allowedInfo.registrableDomain &&
+      requestInfo.registrableDomain === allowedInfo.registrableDomain &&
+      allowedInfo.hostname === allowedInfo.registrableDomain
+    ) {
+      return true;
+    }
+  }
+
+  return false;
+}

package/src/tools/credentials/host-pattern-match.ts

@@ -0,0 +1,60 @@
+/**
+ * Shared host-pattern matching primitive.
+ *
+ * Provides deterministic, case-insensitive hostname matching against
+ * glob-style patterns (e.g. "*.fal.run") with configurable apex inclusion.
+ * Used by the credential selection, proxy router, and policy engines.
+ */
+
+export type HostMatchKind = 'none' | 'wildcard' | 'exact';
+
+export interface MatchHostPatternOptions {
+  /** When true, "*.domain" also matches bare "domain". Defaults to false. */
+  includeApexForWildcard?: boolean;
+}
+
+/**
+ * Match a hostname against a glob-style host pattern.
+ *
+ * Supports:
+ * - Exact match: "api.fal.run" matches "api.fal.run"
+ * - Wildcard match: "*.fal.run" matches "api.fal.run"
+ * - Apex inclusion (opt-in): "*.fal.run" matches "fal.run"
+ *
+ * All comparisons are case-insensitive.
+ */
+export function matchHostPattern(
+  host: string,
+  pattern: string,
+  options?: MatchHostPatternOptions,
+): HostMatchKind {
+  const lHost = host.toLowerCase();
+  const lPattern = pattern.toLowerCase();
+
+  if (lHost === lPattern) return 'exact';
+
+  if (lPattern.startsWith('*.')) {
+    const suffix = lPattern.slice(1); // ".fal.run"
+    // Subdomain match: "api.fal.run".endsWith(".fal.run") and is longer
+    if (lHost.endsWith(suffix) && lHost.length > suffix.length) {
+      return 'wildcard';
+    }
+    // Apex inclusion: "*.fal.run" matches bare "fal.run"
+    if (options?.includeApexForWildcard && lHost === lPattern.slice(2)) {
+      return 'wildcard';
+    }
+  }
+
+  return 'none';
+}
+
+/**
+ * Compare two match results by specificity.
+ * Returns negative if `a` is more specific, positive if `b` is, zero if equal.
+ *
+ * Ordering: exact > wildcard > none
+ */
+export function compareMatchSpecificity(a: HostMatchKind, b: HostMatchKind): number {
+  const rank: Record<HostMatchKind, number> = { exact: 2, wildcard: 1, none: 0 };
+  return rank[b] - rank[a];
+}