@mycadet/credential-executor 0.0.1 → 0.12.6-dev.202610080043.b727a33

package/Dockerfile

@@ -0,0 +1,84 @@
+# syntax=docker/dockerfile:1.20@sha256:26147acbda4f14c5add9946e2fd2ed543fc402884fd75146bd342a7f6271dc1d
+# Build stage
+FROM debian:trixie@sha256:3615a749858a1cba49b408fb49c37093db813321355a9ab7c1f9f4836341e9db AS builder
+
+WORKDIR /app
+
+# Install build dependencies
+RUN apt-get update && apt-get install -y \
+    curl \
+    unzip \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install bun (pinned version)
+RUN curl -fsSL https://bun.sh/install | bash -s "bun-v1.3.11"
+ENV PATH="/root/.bun/bin:${PATH}"
+
+# We must include every workspace member's manifest to validate and install the
+# workspace lockfile via --frozen-lockfile.
+# Note that we don't need source code to resolve cross-workspace dependencies.
+COPY package.json bun.lock ./
+COPY patches ./patches
+COPY --parents clients/*/package.json ./
+COPY cli/package.json ./cli/
+COPY gateway/package.json ./gateway/
+COPY credential-executor/package.json ./credential-executor/
+COPY assistant/package.json ./assistant/
+COPY assistant/src/api/package.json ./assistant/src/api/
+COPY --parents packages/*/package.json ./
+
+RUN --mount=type=cache,id=bun-install-cache,target=/root/.bun/install/cache \
+    bun install --frozen-lockfile --ignore-scripts \
+    --filter='./credential-executor'
+
+# Runtime stage
+FROM debian:trixie-slim@sha256:1d3c811171a08a5adaa4a163fbafd96b61b87aa871bbc7aa15431ac275d3d430 AS runner
+
+WORKDIR /app/credential-executor
+
+RUN apt-get update && apt-get install -y \
+    ca-certificates \
+    e2fsprogs \
+    mount \
+    util-linux \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy bun binary from builder
+COPY --from=builder /root/.bun/bin/bun /usr/local/bin/bun
+RUN ln -sf /usr/local/bin/bun /usr/local/bin/bunx
+
+# Create non-root user
+RUN groupadd --system --gid 1001 ces && \
+    useradd --system --uid 1001 --gid ces --create-home ces
+
+COPY --link --from=builder --chown=1001:1001 /app /app
+
+# Copy source after installing dependencies for better layer caching.
+COPY --chown=ces:ces packages/service-contracts /app/packages/service-contracts
+COPY --chown=ces:ces packages/credential-storage /app/packages/credential-storage
+COPY --chown=ces:ces packages/egress-proxy /app/packages/egress-proxy
+COPY --chown=ces:ces packages/ipc-server-utils /app/packages/ipc-server-utils
+COPY --chown=ces:ces credential-executor ./
+
+# Pre-create /ces-data so the non-root ces user can write to it
+# when no PVC volume is mounted (e.g., direct docker run)
+RUN mkdir -p /ces-data && chown ces:ces /ces-data
+
+# Pre-create /ces-security for credential key storage (keys.enc, store.key)
+RUN mkdir -p /ces-security && chown ces:ces /ces-security
+
+COPY packages/block-volume-bootstrap/scripts/*.sh /usr/local/bin/
+RUN chmod +x \
+    /usr/local/bin/cadet-block-volume-common.sh \
+    /usr/local/bin/cadet-block-volume-init.sh \
+    /usr/local/bin/cadet-block-volume-mount.sh \
+    /usr/local/bin/cadet-block-volume-resize.sh
+
+USER ces
+
+EXPOSE 8090
+
+ENV CES_MODE=managed
+ENV CES_HEALTH_PORT=8090
+
+CMD ["bun", "run", "src/main.ts"]

package/eslint.config.mjs

@@ -0,0 +1,23 @@
+import { defineConfig, globalIgnores } from "eslint/config";
+import tseslint from "typescript-eslint";
+
+const eslintConfig = defineConfig([
+  ...tseslint.configs.recommended,
+  globalIgnores(["dist/**"]),
+  {
+    rules: {
+      "@typescript-eslint/no-unused-vars": [
+        "error",
+        { argsIgnorePattern: "^_", varsIgnorePattern: "^_" },
+      ],
+    },
+  },
+  {
+    files: ["src/__tests__/**"],
+    rules: {
+      "@typescript-eslint/no-explicit-any": "off",
+    },
+  },
+]);
+
+export default eslintConfig;

package/knip.json

@@ -0,0 +1,10 @@
+{
+  "entry": ["src/**/*.test.ts", "src/**/__tests__/**/*.ts"],
+  "project": ["src/**/*.ts"],
+  "ignoreDependencies": [
+    "@mycadet/service-contracts",
+    "@mycadet/credential-storage",
+    "@mycadet/egress-proxy",
+    "@mycadet/ipc-server-utils"
+  ]
+}

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

@@ -0,0 +1,18 @@
+{
+  "name": "@mycadet/credential-storage",
+  "version": "0.0.1",
+  "private": true,
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "typecheck": "bunx tsc --noEmit",
+    "test": "bun test src/"
+  },
+  "devDependencies": {
+    "@types/bun": "1.3.10",
+    "typescript": "5.9.3"
+  }
+}

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

@@ -0,0 +1,177 @@
+/**
+ * Package boundary tests for @mycadet/credential-storage.
+ *
+ * Ensures the package:
+ * 1. Does NOT import from the assistant daemon or CES modules.
+ * 2. Does NOT import from x-client packages (@mycadet/assistant-client,
+ *    @mycadet/ces-client, @mycadet/gateway-client).
+ * 3. Does NOT import from @mycadet/service-contracts runtime/internal modules
+ *    (the aggregate root or any subpath beyond what credential-storage needs
+ *    for pure type definitions is not required at all).
+ * 4. Exposes only local storage/runtime abstractions.
+ * 5. 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|@mycadet\/assistant)(?:\/|["'])/,
+  /require\s*\(\s*["'](?:\.\.\/)*(?:assistant|@mycadet\/assistant)(?:\/|["'])/,
+
+  // CES modules (credential execution service)
+  /from\s+["'].*\/ces\//,
+  /require\s*\(\s*["'].*\/ces\//,
+  /from\s+["']@mycadet\/ces/,
+  /require\s*\(\s*["']@mycadet\/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/,
+
+  // x-client packages (must not depend on any typed service client)
+  /from\s+["']@mycadet\/assistant-client(?:\/|["'])/,
+  /require\s*\(\s*["']@mycadet\/assistant-client(?:\/|["'])/,
+  /from\s+["']@mycadet\/ces-client(?:\/|["'])/,
+  /require\s*\(\s*["']@mycadet\/ces-client(?:\/|["'])/,
+  /from\s+["']@mycadet\/gateway-client(?:\/|["'])/,
+  /require\s*\(\s*["']@mycadet\/gateway-client(?:\/|["'])/,
+
+  // service-contracts aggregate root or internal subpaths
+  // credential-storage is a lower-layer package and must not depend on
+  // service-contracts (which sits at the same layer but deals with RPC
+  // protocol types, not storage abstractions).
+  /from\s+["']@mycadet\/service-contracts(?:\/|["'])/,
+  /require\s*\(\s*["']@mycadet\/service-contracts(?:\/|["'])/,
+];
+
+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, CES, x-client, or service-contracts 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, CES, x-client, or service-contracts 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("daemon") ||
+        [
+          "@mycadet/ces-client",
+          "@mycadet/ces-contracts",
+          "@mycadet/service-contracts",
+          "@mycadet/assistant-client",
+          "@mycadet/gateway-client",
+        ].includes(dep),
+    );
+    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/@mycadet/credential-storage/src/index.ts

@@ -0,0 +1,218 @@
+/**
+ * @mycadet/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. 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. "google", "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";