@vellumai/credential-executor 0.4.55 → 0.4.56

package/src/http/path-template.ts

@@ -14,6 +14,23 @@
  * - Trailing slashes are normalised away.
  */
 
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Safely decode a percent-encoded path segment. Returns `null` when it
+ * contains malformed escapes (e.g. bare `%` or `%zz`) so that callers
+ * can fail closed — malformed segments never match anything.
+ */
+function safeDecodeSegment(segment: string): string | null {
+  try {
+    return decodeURIComponent(segment);
+  } catch {
+    return null;
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Segment classification patterns
 // ---------------------------------------------------------------------------
@@ -37,6 +54,21 @@ const NUMERIC_RE = /^[0-9]+$/;
  */
 const HEX_LONG_RE = /^[0-9a-f]{16,}$/i;
 
+// ---------------------------------------------------------------------------
+// Spoofed placeholder detection
+// ---------------------------------------------------------------------------
+
+/**
+ * Literal strings that, if present in a decoded URL segment, indicate an
+ * attempt to inject a wildcard placeholder via percent-encoding.
+ *
+ * Legitimate URLs never contain these exact strings as path segments.
+ * Rejecting them prevents an attacker from crafting a URL like
+ * `https://api.example.com/%7B:num%7D/resource` that would be stored as
+ * a literal during grant approval but decoded to a wildcard during matching.
+ */
+const PLACEHOLDER_LITERALS = new Set(["{:num}", "{:uuid}", "{:hex}"]);
+
 // ---------------------------------------------------------------------------
 // Placeholder types
 // ---------------------------------------------------------------------------
@@ -73,12 +105,40 @@ export function derivePathTemplate(rawUrl: string): string {
   const scheme = parsed.protocol.replace(/:$/, "");
   const host = parsed.hostname + (parsed.port ? `:${parsed.port}` : "");
 
-  // Split path into segments, dropping empty segments from leading/trailing slashes
-  const segments = parsed.pathname
+  // Split path into segments, dropping empty segments from leading/trailing slashes.
+  const rawSegments = parsed.pathname
     .split("/")
     .filter((s) => s.length > 0);
 
-  const templatedSegments = segments.map(classifySegment);
+  // Decode each segment for classification and placeholder detection, but
+  // preserve the raw (encoded) form for literal segments in the rebuilt
+  // template. This prevents encoded delimiters like %2F from being decoded
+  // into real path separators, which would change URL structure.
+  const decodedSegments = rawSegments.map((seg) => {
+    const decoded = safeDecodeSegment(seg);
+    // If decoding fails, keep the raw segment — it will be stored as a
+    // literal and can never match anything meaningful (fail closed).
+    return decoded ?? seg;
+  });
+
+  // Guard: reject URLs whose decoded segments match known placeholder
+  // patterns. Legitimate URLs never contain literal "{:num}" etc. as path
+  // segments; their presence indicates an attempt to inject wildcards via
+  // percent-encoding (e.g. %7B:num%7D).
+  for (const seg of decodedSegments) {
+    if (PLACEHOLDER_LITERALS.has(seg)) {
+      throw new Error(
+        `Refusing to derive path template: segment "${seg}" is a reserved placeholder literal`,
+      );
+    }
+  }
+
+  const templatedSegments = decodedSegments.map((decoded, i) => {
+    const classified = classifySegment(decoded);
+    // If the segment was replaced with a placeholder, use the placeholder.
+    // Otherwise, use the raw (encoded) segment to preserve URL structure.
+    return classified !== decoded ? classified : rawSegments[i]!;
+  });
 
   const path =
     templatedSegments.length > 0
@@ -147,21 +207,27 @@ export function urlMatchesTemplate(
   if (urlHost !== templateHost) return false;
 
   // Split paths and compare segment-by-segment.
-  // decodeURIComponent is needed because the URL constructor percent-encodes
-  // curly braces ({, }) in paths — placeholders like {:num} become %7B:num%7D.
+  // safeDecodeSegment is applied to both sides so that percent-encoded bytes
+  // (e.g. %20, %7B) are compared consistently and so that the URL constructor's
+  // encoding of curly braces ({, }) in template placeholders is reversed.
+  // A null return means a malformed escape — fail closed immediately.
   const urlSegments = parsedUrl.pathname
     .split("/")
-    .filter((s) => s.length > 0);
+    .filter((s) => s.length > 0)
+    .map(safeDecodeSegment);
   const templateSegments = parsedTemplate.pathname
     .split("/")
     .filter((s) => s.length > 0)
-    .map((s) => decodeURIComponent(s));
+    .map(safeDecodeSegment);
+
+  if (urlSegments.some((s) => s === null)) return false;
+  if (templateSegments.some((s) => s === null)) return false;
 
   if (urlSegments.length !== templateSegments.length) return false;
 
   for (let i = 0; i < templateSegments.length; i++) {
-    const tSeg = templateSegments[i];
-    const uSeg = urlSegments[i];
+    const tSeg = templateSegments[i]!;
+    const uSeg = urlSegments[i]!;
 
     if (tSeg === "{:num}") {
       if (!NUMERIC_RE.test(uSeg)) return false;

package/src/http/policy.ts

@@ -18,9 +18,7 @@
  *   credential.
  */
 
-import { createHash } from "node:crypto";
-
-import type { HttpGrantProposal } from "@vellumai/ces-contracts";
+import { hashProposal, type HttpGrantProposal } from "@vellumai/ces-contracts";
 
 import type { PersistentGrant, PersistentGrantStore } from "../grants/persistent-store.js";
 import type { TemporaryGrantStore } from "../grants/temporary-store.js";
@@ -93,7 +91,7 @@ export interface HttpPolicyRequest {
   purpose: string;
   /** Explicit grant ID the caller claims to hold. */
   grantId?: string;
-  /** Conversation ID for thread-scoped temporary grants. */
+  /** Conversation ID for conversation-scoped temporary grants. */
   conversationId?: string;
 }
 
@@ -129,10 +127,14 @@ export function evaluateHttpPolicy(
   // 2. Check explicit grantId in persistent store
   if (request.grantId) {
     const grant = persistentStore.getById(request.grantId);
-    if (grant) {
+    if (
+      grant &&
+      grant.tool === "http" &&
+      grantCoversRequest(grant, request.credentialHandle, request.method, request.url, "")
+    ) {
       return { allowed: true, grantId: grant.id, grantSource: "persistent" };
     }
-    // Explicit grant not found — fall through to pattern matching
+    // Explicit grant not found or does not cover this request — fall through to pattern matching
   }
 
   // 3. Check persistent grants for pattern match
@@ -150,7 +152,7 @@ export function evaluateHttpPolicy(
   // 4. Check temporary grants
   // Build a proposal hash key from the canonical request shape
   const proposal = buildProposal(request, pathTemplate);
-  const proposalHash = hashProposalForLookup(proposal);
+  const proposalHash = hashProposal(proposal);
 
   const tempKind = temporaryStore.checkAny(
     proposalHash,
@@ -234,23 +236,3 @@ function buildProposal(
   };
 }
 
-/**
- * Compute a deterministic hash key for temporary grant lookup.
- *
- * Uses the same canonical JSON → SHA-256 approach as the contracts package
- * `hashProposal`, but we use a simplified inline version here to avoid
- * importing the full contracts rendering module into the policy hot path.
- */
-function hashProposalForLookup(proposal: HttpGrantProposal): string {
-  // Build a canonical key from the proposal's stable fields:
-  // type + credentialHandle + method + allowedUrlPatterns (sorted)
-  const parts = [
-    proposal.type,
-    proposal.credentialHandle,
-    proposal.method.toUpperCase(),
-    ...(proposal.allowedUrlPatterns ?? []).slice().sort(),
-  ];
-  const canonical = JSON.stringify(parts);
-
-  return createHash("sha256").update(canonical, "utf8").digest("hex");
-}

package/src/index.ts

@@ -29,6 +29,7 @@ export type {
   RpcHandlerRegistry,
   RpcMethodHandler,
   RunAuthenticatedCommandHandlerOptions,
+  SessionIdRef,
 } from "./server.js";
 
 export {
@@ -104,3 +105,5 @@ export type {
 
 export { executeAuthenticatedHttpRequest } from "./http/executor.js";
 export type { HttpExecutorDeps } from "./http/executor.js";
+
+export { MANAGED_LOCAL_STATIC_REJECTION_ERROR } from "./managed-errors.js";

package/src/main.ts

@@ -36,6 +36,11 @@ import {
 } from "./grants/rpc-handlers.js";
 import { TemporaryGrantStore } from "./grants/temporary-store.js";
 import { LocalMaterialiser } from "./materializers/local.js";
+import { createLocalSecureKeyBackend } from "./materializers/local-secure-key-backend.js";
+import { createLocalOAuthLookup } from "./materializers/local-oauth-lookup.js";
+import { createLocalTokenRefreshFn } from "./materializers/local-token-refresh.js";
+import { resolveLocalSubject } from "./subjects/local.js";
+import { checkCredentialPolicy } from "./subjects/policy.js";
 import {
   getCesAuditDir,
   getCesDataRoot,
@@ -48,9 +53,11 @@ import {
   registerCommandExecutionHandler,
   registerManageSecureCommandToolHandler,
   type RpcHandlerRegistry,
+  type SessionIdRef,
 } from "./server.js";
-import { publishBundle } from "./toolstore/publish.js";
-import type { OAuthConnectionLookup } from "./subjects/local.js";
+import { deleteBundleFromToolstore, publishBundle } from "./toolstore/publish.js";
+import { validateSourceUrl } from "./toolstore/manifest.js";
+import { buildCesEgressHooks } from "./commands/egress-hooks.js";
 
 // ---------------------------------------------------------------------------
 // Data directory bootstrap
@@ -81,7 +88,7 @@ function getVellumRootDir(): string {
 // Build RPC handler registry
 // ---------------------------------------------------------------------------
 
-function buildHandlers(sessionId: string): RpcHandlerRegistry {
+function buildHandlers(sessionIdRef: SessionIdRef): RpcHandlerRegistry {
   // -- Grant stores ----------------------------------------------------------
   const persistentGrantStore = new PersistentGrantStore(
     getCesGrantsDir("local"),
@@ -100,41 +107,26 @@ function buildHandlers(sessionId: string): RpcHandlerRegistry {
   const vellumRoot = getVellumRootDir();
   const credentialMetadataPath = join(
     vellumRoot,
+    "workspace",
     "data",
-    "credential-metadata.json",
+    "credentials",
+    "metadata.json",
   );
   const metadataStore = new StaticCredentialMetadataStore(
     credentialMetadataPath,
   );
 
-  // Stub OAuth connection lookup — local OAuth connections are resolved from
-  // the assistant's SQLite database which CES cannot access directly. When
-  // local OAuth execution is needed, a connection bridge must be added.
-  const oauthConnections: OAuthConnectionLookup = {
-    getById: () => undefined,
-  };
+  // Read-only OAuth connection lookup backed by the assistant's SQLite
+  // database. CES opens the database in read-only mode.
+  const oauthConnections = createLocalOAuthLookup(vellumRoot);
 
-  // Stub SecureKeyBackend — in local mode the backend implementation lives in
-  // the assistant process (keychain or encrypted file store). CES cannot import
-  // it directly. HTTP/command handlers that require credential materialisation
-  // will return a structured error until a CES-native backend is wired in.
-  const stubSecureKeyBackend = {
-    async get(_key: string) {
-      return undefined;
-    },
-    async set(_key: string, _value: string) {
-      return false;
-    },
-    async delete(_key: string) {
-      return "error" as const;
-    },
-    async list() {
-      return [];
-    },
-  };
+  // CES-native SecureKeyBackend that reads from the assistant's encrypted
+  // key store file. Read-only — CES never writes or deletes keys.
+  const secureKeyBackend = createLocalSecureKeyBackend(vellumRoot);
 
   const localMaterialiser = new LocalMaterialiser({
-    secureKeyBackend: stubSecureKeyBackend,
+    secureKeyBackend,
+    tokenRefreshFn: createLocalTokenRefreshFn(vellumRoot, secureKeyBackend),
   });
 
   // -- Build handler registry ------------------------------------------------
@@ -149,7 +141,8 @@ function buildHandlers(sessionId: string): RpcHandlerRegistry {
         metadataStore,
         oauthConnections,
       },
-      sessionId,
+      auditStore,
+      sessionId: sessionIdRef,
     },
   );
 
@@ -158,13 +151,41 @@ function buildHandlers(sessionId: string): RpcHandlerRegistry {
     executorDeps: {
       persistentStore: persistentGrantStore,
       temporaryStore: temporaryGrantStore,
-      materializeCredential: async (_handle) => ({
-        ok: false as const,
-        error:
-          "CES local credential materialisation not yet available. " +
-          "A CES-native secure-key backend must be configured.",
-      }),
+      materializeCredential: async (handle) => {
+        // Resolve the subject first, then materialise through the local backend
+        const subjectResult = resolveLocalSubject(handle, {
+          metadataStore,
+          oauthConnections,
+        });
+        if (!subjectResult.ok) {
+          return { ok: false as const, error: subjectResult.error };
+        }
+
+        // Enforce credential-level policies for local static handles
+        if (subjectResult.subject.type === "local_static") {
+          const policyCheck = checkCredentialPolicy(
+            subjectResult.subject.metadata,
+            "run_authenticated_command",
+          );
+          if (!policyCheck.ok) {
+            return { ok: false as const, error: policyCheck.error! };
+          }
+        }
+
+        const matResult = await localMaterialiser.materialise(subjectResult.subject);
+        if (!matResult.ok) {
+          return { ok: false as const, error: matResult.error };
+        }
+        return {
+          ok: true as const,
+          value: matResult.credential.value,
+          handleType: matResult.credential.handleType,
+        };
+      },
+      auditStore,
+      sessionId: sessionIdRef,
       cesMode: "local",
+      egressHooks: buildCesEgressHooks(),
     },
     defaultWorkspaceDir: join(vellumRoot, "workspace"),
   });
@@ -174,15 +195,47 @@ function buildHandlers(sessionId: string): RpcHandlerRegistry {
 
   registerManageSecureCommandToolHandler(handlers, {
     downloadBundle: async (sourceUrl: string) => {
-      const resp = await fetch(sourceUrl);
+      const urlError = validateSourceUrl(sourceUrl);
+      if (urlError) {
+        throw new Error(urlError);
+      }
+      const MAX_BUNDLE_SIZE = 100 * 1024 * 1024; // 100 MB
+      const resp = await fetch(sourceUrl, { signal: AbortSignal.timeout(60_000) });
       if (!resp.ok) {
         throw new Error(`HTTP ${resp.status}: ${resp.statusText}`);
       }
-      return Buffer.from(await resp.arrayBuffer());
+      const contentLength = resp.headers.get("content-length");
+      if (contentLength && parseInt(contentLength, 10) > MAX_BUNDLE_SIZE) {
+        throw new Error(`Bundle too large: ${contentLength} bytes (max ${MAX_BUNDLE_SIZE})`);
+      }
+      // Stream the body and enforce the size limit on actual bytes received,
+      // since Content-Length can be absent (chunked encoding) or lie.
+      const body = resp.body;
+      if (!body) {
+        throw new Error("Response body is null");
+      }
+      const chunks: Uint8Array[] = [];
+      let totalBytes = 0;
+      for await (const chunk of body) {
+        totalBytes += chunk.byteLength;
+        if (totalBytes > MAX_BUNDLE_SIZE) {
+          throw new Error(`Bundle too large: received >${MAX_BUNDLE_SIZE} bytes (max ${MAX_BUNDLE_SIZE})`);
+        }
+        chunks.push(chunk);
+      }
+      return Buffer.concat(chunks);
     },
     publishBundle: (request) => publishBundle({ ...request, cesMode: "local" }),
     unregisterTool: (toolName: string) => {
-      return toolRegistry.delete(toolName);
+      const entry = toolRegistry.get(toolName);
+      const removed = toolRegistry.delete(toolName);
+      if (removed && entry?.bundleDigest) {
+        const stillInUse = Array.from(toolRegistry.values()).some(t => t.bundleDigest === entry.bundleDigest);
+        if (!stillInUse) {
+          deleteBundleFromToolstore(entry.bundleDigest, "local");
+        }
+      }
+      return removed;
     },
     registerTool: (entry) => {
       toolRegistry.set(entry.toolName, entry);
@@ -197,7 +250,6 @@ function buildHandlers(sessionId: string): RpcHandlerRegistry {
 
   handlers[CesRpcMethod.ListGrants] = createListGrantsHandler({
     persistentGrantStore,
-    sessionId,
   }) as typeof handlers[string];
 
   handlers[CesRpcMethod.RevokeGrant] = createRevokeGrantHandler({
@@ -234,9 +286,11 @@ async function main(): Promise<void> {
   process.on("SIGTERM", shutdown);
   process.on("SIGINT", shutdown);
 
-  // Build the handler registry with all available RPC implementations
-  const sessionId = `ces-local-${Date.now()}`;
-  const handlers = buildHandlers(sessionId);
+  // Build the handler registry with all available RPC implementations.
+  // Use a mutable ref so audit records capture the handshake session ID
+  // once it's negotiated (the handshake completes before any RPC call).
+  const sessionIdRef: SessionIdRef = { current: `ces-local-${Date.now()}` };
+  const handlers = buildHandlers(sessionIdRef);
 
   const server = new CesRpcServer({
     input: process.stdin,
@@ -251,6 +305,11 @@ async function main(): Promise<void> {
         process.stderr.write(`[ces-local] ERROR: ${msg} ${args.map(String).join(" ")}\n`),
     },
     signal: controller.signal,
+    onHandshakeComplete: (hsSessionId) => {
+      sessionIdRef.current = hsSessionId;
+    },
+    // Local mode reads API keys from env/store directly — no-op handler.
+    onApiKeyUpdate: () => {},
   });
 
   await server.serve();

package/src/managed-errors.ts

@@ -0,0 +1,9 @@
+/**
+ * Error message constants for managed-mode CES.
+ *
+ * Re-exported from @vellumai/ces-contracts so both the assistant and
+ * credential-executor can share the constant via the approved shared-code
+ * path without violating the hard process-boundary isolation.
+ */
+
+export { MANAGED_LOCAL_STATIC_REJECTION_ERROR } from "@vellumai/ces-contracts";

package/src/managed-lazy-getters.ts

@@ -0,0 +1,70 @@
+/**
+ * Lazy getter pattern for managed CES API key propagation.
+ *
+ * In managed mode the assistant API key may arrive after CES handlers are
+ * registered (via the handshake callback or a later RPC update). The
+ * `ApiKeyRef` + `buildLazyGetters` pattern allows handlers to resolve
+ * the key at call time rather than at registration time.
+ *
+ * Extracted from `managed-main.ts` so the behavioral contract can be
+ * tested directly without exercising the full managed bootstrap lifecycle.
+ */
+
+import type { ManagedSubjectResolverOptions } from "./subjects/managed.js";
+import type { ManagedMaterializerOptions } from "./materializers/managed-platform.js";
+
+/**
+ * Mutable reference to the assistant API key. Allows the handshake callback
+ * to inject the key provisioned at runtime (which arrives after handlers are
+ * built). Handlers read `.current` at call time, not at registration time.
+ */
+export interface ApiKeyRef {
+  current: string;
+}
+
+export interface LazyGetterOptions {
+  platformBaseUrl: string;
+  assistantId: string;
+  apiKeyRef: ApiKeyRef;
+  envApiKey?: string;
+}
+
+export interface LazyGetters {
+  getAssistantApiKey: () => string;
+  getManagedSubjectOptions: () => ManagedSubjectResolverOptions | undefined;
+  getManagedMaterializerOptions: () => ManagedMaterializerOptions | undefined;
+}
+
+/**
+ * Build lazy getter functions that resolve the API key at call time.
+ *
+ * Prefers the handshake-provided key (via `apiKeyRef.current`) over the
+ * env-var fallback, since in managed mode the env var may not be set
+ * (chicken-and-egg: key is provisioned after hatch).
+ */
+export function buildLazyGetters(opts: LazyGetterOptions): LazyGetters {
+  const { platformBaseUrl, assistantId, apiKeyRef, envApiKey } = opts;
+
+  const getAssistantApiKey = (): string =>
+    apiKeyRef.current || envApiKey || "";
+
+  const getManagedSubjectOptions = (): ManagedSubjectResolverOptions | undefined => {
+    const key = getAssistantApiKey();
+    return platformBaseUrl && key && assistantId
+      ? { platformBaseUrl, assistantApiKey: key, assistantId }
+      : undefined;
+  };
+
+  const getManagedMaterializerOptions = (): ManagedMaterializerOptions | undefined => {
+    const key = getAssistantApiKey();
+    return platformBaseUrl && key && assistantId
+      ? { platformBaseUrl, assistantApiKey: key, assistantId }
+      : undefined;
+  };
+
+  return {
+    getAssistantApiKey,
+    getManagedSubjectOptions,
+    getManagedMaterializerOptions,
+  };
+}