@vellumai/credential-executor 0.4.55 → 0.4.56

package/node_modules/@vellumai/credential-storage/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@vellumai/credential-storage",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "typecheck": "bunx tsc --noEmit",
+    "test": "bun test src/"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.2.4",
+    "typescript": "^5.7.3"
+  }
+}

package/node_modules/@vellumai/credential-storage/src/__tests__/package-boundary.test.ts

@@ -0,0 +1,151 @@
+/**
+ * Package boundary tests for @vellumai/credential-storage.
+ *
+ * Ensures the package:
+ * 1. Does NOT import from the assistant daemon or CES modules.
+ * 2. Exposes only local storage/runtime abstractions.
+ * 3. Remains portable and self-contained.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+const PACKAGE_ROOT = resolve(import.meta.dirname, "../..");
+const SRC_DIR = join(PACKAGE_ROOT, "src");
+
+/**
+ * Recursively collect all .ts files under a directory, excluding test files.
+ */
+function collectSourceFiles(dir: string): string[] {
+  const files: string[] = [];
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    const stat = statSync(full);
+    if (stat.isDirectory()) {
+      if (entry === "node_modules" || entry === "__tests__") continue;
+      files.push(...collectSourceFiles(full));
+    } else if (entry.endsWith(".ts") && !entry.endsWith(".test.ts")) {
+      files.push(full);
+    }
+  }
+  return files;
+}
+
+/**
+ * Patterns that must NOT appear in any import/require statement within
+ * source files. These catch imports from the assistant daemon, CES,
+ * or other modules this package should never depend on.
+ */
+const FORBIDDEN_IMPORT_PATTERNS = [
+  // Assistant daemon internals (blocks both sub-path and root entrypoint imports)
+  /from\s+["'](?:\.\.\/)*(?:assistant|@vellumai\/assistant)(?:\/|["'])/,
+  /require\s*\(\s*["'](?:\.\.\/)*(?:assistant|@vellumai\/assistant)(?:\/|["'])/,
+
+  // CES modules (credential execution service)
+  /from\s+["'].*\/ces\//,
+  /require\s*\(\s*["'].*\/ces\//,
+  /from\s+["']@vellumai\/ces/,
+  /require\s*\(\s*["']@vellumai\/ces/,
+
+  // Direct runtime/daemon imports
+  /from\s+["'].*\/runtime\//,
+  /require\s*\(\s*["'].*\/runtime\//,
+  /from\s+["'].*\/daemon\//,
+  /require\s*\(\s*["'].*\/daemon\//,
+
+  // Direct config/tools imports from assistant
+  /from\s+["'].*\/config\/loader/,
+  /from\s+["'].*\/tools\//,
+  /from\s+["'].*\/oauth\/oauth-store/,
+  /from\s+["'].*\/security\/secure-keys/,
+];
+
+describe("package boundary", () => {
+  const sourceFiles = collectSourceFiles(SRC_DIR);
+
+  test("has source files to validate", () => {
+    expect(sourceFiles.length).toBeGreaterThan(0);
+  });
+
+  test("does not import from assistant or CES modules", () => {
+    const violations: string[] = [];
+
+    for (const file of sourceFiles) {
+      const content = readFileSync(file, "utf-8");
+      const lines = content.split("\n");
+
+      for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        for (const pattern of FORBIDDEN_IMPORT_PATTERNS) {
+          if (pattern.test(line)) {
+            const relative = file.replace(PACKAGE_ROOT + "/", "");
+            violations.push(`${relative}:${i + 1}: ${line.trim()}`);
+          }
+        }
+      }
+    }
+
+    if (violations.length > 0) {
+      throw new Error(
+        `Found ${violations.length} forbidden import(s) in credential-storage package:\n` +
+          violations.map((v) => `  - ${v}`).join("\n"),
+      );
+    }
+  });
+
+  test("package.json declares it as private", () => {
+    const pkg = JSON.parse(
+      readFileSync(join(PACKAGE_ROOT, "package.json"), "utf-8"),
+    );
+    expect(pkg.private).toBe(true);
+  });
+
+  test("package.json does not depend on assistant or CES packages", () => {
+    const pkg = JSON.parse(
+      readFileSync(join(PACKAGE_ROOT, "package.json"), "utf-8"),
+    );
+    const allDeps = {
+      ...pkg.dependencies,
+      ...pkg.devDependencies,
+      ...pkg.peerDependencies,
+    };
+    const forbidden = Object.keys(allDeps).filter(
+      (dep) =>
+        dep.includes("assistant") ||
+        dep.includes("ces") ||
+        dep.includes("daemon"),
+    );
+    expect(forbidden).toEqual([]);
+  });
+});
+
+describe("public API surface", () => {
+  test("exports credential record types", async () => {
+    const mod = await import("../../src/index.js");
+
+    // Verify credentialKey function is exported and works
+    expect(typeof mod.credentialKey).toBe("function");
+    expect(mod.credentialKey("github", "api_key")).toBe(
+      "credential/github/api_key",
+    );
+  });
+
+  test("exports only local storage/runtime abstractions", async () => {
+    const mod = await import("../../src/index.js");
+    const exportedNames = Object.keys(mod);
+
+    // Should export the credentialKey utility
+    expect(exportedNames).toContain("credentialKey");
+
+    // Should NOT export anything CES-specific or assistant-specific
+    const forbidden = exportedNames.filter(
+      (name) =>
+        name.toLowerCase().includes("daemon") ||
+        name.toLowerCase().includes("ces") ||
+        name.toLowerCase().includes("agentloop") ||
+        name.toLowerCase().includes("toolexecutor"),
+    );
+    expect(forbidden).toEqual([]);
+  });
+});

package/node_modules/@vellumai/credential-storage/src/index.ts

@@ -0,0 +1,213 @@
+/**
+ * @vellumai/credential-storage
+ *
+ * Local credential persistence and materialization primitives.
+ *
+ * This package provides neutral interfaces for:
+ * - Local static credential metadata records
+ * - OAuth connection records persisted on the local runtime
+ * - Secure-key lookup abstractions
+ * - Token persistence and refresh helpers
+ *
+ * It is explicitly scoped to LOCAL storage and runtime concerns.
+ * It must NOT import from the assistant daemon, CES, or any
+ * service-specific module. Later extraction PRs will move existing
+ * assistant logic into this package without changing behavior.
+ */
+
+// ---------------------------------------------------------------------------
+// Static credential metadata
+// ---------------------------------------------------------------------------
+
+/**
+ * Non-secret metadata about a locally stored credential.
+ * Secret values remain in the secure-key backend only.
+ */
+export interface StaticCredentialRecord {
+  /** Opaque identifier for this credential. */
+  credentialId: string;
+  /** Service name (e.g. "github", "fal"). */
+  service: string;
+  /** Field name within the service (e.g. "api_key", "password"). */
+  field: string;
+  /** Tools permitted to consume this credential. */
+  allowedTools: string[];
+  /** Domains where this credential may be used. */
+  allowedDomains: string[];
+  /** Human-readable description of intended usage. */
+  usageDescription?: string;
+  /** Human-friendly alias (e.g. "fal-primary"). */
+  alias?: string;
+  /** Templates describing how to inject this credential into proxied requests. */
+  injectionTemplates?: InjectionTemplate[];
+  /** Epoch ms when the record was created. */
+  createdAt: number;
+  /** Epoch ms when the record was last updated. */
+  updatedAt: number;
+}
+
+/**
+ * Describes how to inject a credential value into an outbound request
+ * matching a specific host pattern.
+ */
+export interface InjectionTemplate {
+  /** Glob pattern for matching request hosts (e.g. "*.fal.ai"). */
+  hostPattern: string;
+  /** Where the credential value is injected. */
+  injectionType: "header" | "query";
+  /** 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;
+}
+
+// ---------------------------------------------------------------------------
+// Secure-key lookup
+// ---------------------------------------------------------------------------
+
+/**
+ * Result of a secure-key deletion attempt.
+ */
+export type SecureKeyDeleteResult = "deleted" | "not-found" | "error";
+
+/**
+ * Abstraction over the underlying secure-key backend (e.g. macOS Keychain,
+ * encrypted file store). Implementations handle platform-specific details.
+ */
+export interface SecureKeyBackend {
+  /** Retrieve a secret value by key. Returns undefined if not found. */
+  get(key: string): Promise<string | undefined>;
+  /** Store a secret value. Returns true on success. */
+  set(key: string, value: string): Promise<boolean>;
+  /** Delete a secret. */
+  delete(key: string): Promise<SecureKeyDeleteResult>;
+  /** List all stored key names. */
+  list(): Promise<string[]>;
+}
+
+// ---------------------------------------------------------------------------
+// OAuth connection records (local persistence)
+// ---------------------------------------------------------------------------
+
+/**
+ * Record of a locally persisted OAuth connection.
+ * Represents a user's authorization grant for a specific provider.
+ */
+export interface OAuthConnectionRecord {
+  /** Unique identifier for this connection. */
+  id: string;
+  /** Provider key (e.g. "integration:google", "integration:slack"). */
+  providerKey: string;
+  /** Account identifier (e.g. email address). */
+  accountInfo: string | null;
+  /** OAuth scopes that were granted. */
+  grantedScopes: string[];
+  /** Secure-key path where the access token is stored. */
+  accessTokenPath: string;
+  /** Whether a refresh token is stored for this connection. */
+  hasRefreshToken: boolean;
+  /** Epoch ms when the token expires (null if unknown). */
+  expiresAt: number | null;
+  /** Epoch ms when the connection was created. */
+  createdAt: number;
+  /** Epoch ms when the connection was last updated. */
+  updatedAt: number;
+}
+
+// ---------------------------------------------------------------------------
+// Token persistence
+// ---------------------------------------------------------------------------
+
+/**
+ * Result of a token refresh attempt.
+ */
+export type TokenRefreshResult =
+  | { success: true; accessToken: string; expiresAt: number | null; refreshToken?: string }
+  | { success: false; error: string };
+
+/**
+ * Abstraction for persisting and refreshing OAuth tokens locally.
+ * Implementations handle token storage, expiry checking, and refresh flows.
+ */
+export interface TokenPersistence {
+  /**
+   * Retrieve a valid access token for a connection, refreshing if necessary.
+   * Returns the access token string or throws if the token cannot be obtained.
+   */
+  getAccessToken(connectionId: string): Promise<string>;
+
+  /**
+   * Persist a new token set (access token, optional refresh token, expiry).
+   */
+  persistTokens(
+    connectionId: string,
+    tokens: {
+      accessToken: string;
+      refreshToken?: string;
+      expiresAt?: number | null;
+    }
+  ): Promise<void>;
+
+  /**
+   * Attempt to refresh the access token for a connection.
+   */
+  refreshToken(connectionId: string): Promise<TokenRefreshResult>;
+
+  /**
+   * Revoke and delete all tokens for a connection.
+   */
+  revokeTokens(connectionId: string): Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// Credential key format
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a credential key for the secure-key store.
+ *
+ * Keys follow the pattern: `credential/{service}/{field}`
+ */
+export function credentialKey(service: string, field: string): string {
+  return `credential/${service}/${field}`;
+}
+
+// ---------------------------------------------------------------------------
+// Static credential metadata store
+// ---------------------------------------------------------------------------
+
+export { StaticCredentialMetadataStore } from "./static-credentials.js";
+export type { StaticCredentialPolicyInput } from "./static-credentials.js";
+
+// ---------------------------------------------------------------------------
+// OAuth runtime primitives
+// ---------------------------------------------------------------------------
+
+export {
+  // Secure-key path conventions
+  oauthConnectionAccessTokenPath,
+  oauthConnectionRefreshTokenPath,
+  oauthAppClientSecretPath,
+  // Token expiry
+  EXPIRY_BUFFER_MS,
+  isTokenExpired,
+  computeExpiresAt,
+  // Circuit breaker
+  REFRESH_FAILURE_THRESHOLD,
+  INITIAL_COOLDOWN_MS,
+  MAX_COOLDOWN_MS,
+  RefreshCircuitBreaker,
+  // Refresh deduplication
+  RefreshDeduplicator,
+  // Credential error classification
+  isCredentialError,
+  // Token persistence helpers
+  persistOAuthTokens,
+  getStoredAccessToken,
+  getStoredRefreshToken,
+  deleteOAuthTokens,
+  persistRefreshedTokens,
+} from "./oauth-runtime.js";
+export type { RefreshBreakerState } from "./oauth-runtime.js";