veryfront 0.1.241 → 0.1.243

package/src/deno.js

@@ -1,6 +1,6 @@
 export default {
   "name": "veryfront",
-  "version": "0.1.241",
+  "version": "0.1.243",
   "license": "Apache-2.0",
   "nodeModulesDir": "auto",
   "workspace": [

package/src/src/agent/conversation-root-run-context.ts

@@ -24,6 +24,8 @@ function normalizeProvidedRun(input: {
     messageId: input.providedRun.messageId,
     latestEventId: input.providedRun.latestEventId ?? 0,
     latestExternalEventSequence: input.providedRun.latestExternalEventSequence ?? 0,
+    waitingToolCallId: null,
+    waitingToolName: null,
     status: "running",
   };
 }

package/src/src/agent/durable.ts

@@ -86,6 +86,10 @@ export const ConversationRunProjectionSchema = z
     latest_event_id: z.number().int().nonnegative().optional(),
     latestExternalEventSequence: z.number().int().nonnegative().optional(),
     latest_external_event_sequence: z.number().int().nonnegative().optional(),
+    waitingToolCallId: z.string().min(1).nullable().optional(),
+    waiting_tool_call_id: z.string().min(1).nullable().optional(),
+    waitingToolName: z.string().nullable().optional(),
+    waiting_tool_name: z.string().nullable().optional(),
     status: ConversationRunStatusSchema,
   })
   .passthrough()
@@ -111,6 +115,8 @@ export const ConversationRunProjectionSchema = z
       messageId,
       latestEventId,
       latestExternalEventSequence,
+      waitingToolCallId: data.waitingToolCallId ?? data.waiting_tool_call_id ?? null,
+      waitingToolName: data.waitingToolName ?? data.waiting_tool_name ?? null,
       status: data.status,
     };
   });
@@ -124,6 +130,10 @@ export type TerminalConversationRunStatus = Extract<
   ConversationRunProjection["status"],
   "completed" | "failed" | "cancelled"
 >;
+export type ConversationRunAppendCursorResyncResult =
+  | "advanced"
+  | "non_appendable"
+  | "unchanged";
 
 export const CreateConversationRunAcceptedSchema = z
   .object({
@@ -322,6 +332,56 @@ export function isActiveConversationRunStatus(
   return status === "pending" || status === "running" || status === "waiting_for_tool";
 }
 
+export function isAppendableConversationRunProjection(run: ConversationRunProjection): boolean {
+  return (
+    run.status !== "completed" &&
+    run.status !== "failed" &&
+    run.status !== "cancelled" &&
+    run.status !== "waiting_for_tool" &&
+    run.waitingToolCallId === null &&
+    run.waitingToolName === null
+  );
+}
+
+export async function resyncConversationRunAppendCursor(input: {
+  authToken: string;
+  apiUrl: string;
+  conversationId: string;
+  runId: string;
+  previousLatestExternalEventSequence: number;
+  abortSignal?: AbortSignal;
+}): Promise<{
+  result: ConversationRunAppendCursorResyncResult;
+  run: ConversationRunProjection;
+}> {
+  const run = await getConversationRun({
+    authToken: input.authToken,
+    apiUrl: input.apiUrl,
+    conversationId: input.conversationId,
+    runId: input.runId,
+    abortSignal: input.abortSignal,
+  });
+
+  if (run.latestExternalEventSequence > input.previousLatestExternalEventSequence) {
+    return {
+      result: "advanced",
+      run,
+    };
+  }
+
+  if (!isAppendableConversationRunProjection(run)) {
+    return {
+      result: "non_appendable",
+      run,
+    };
+  }
+
+  return {
+    result: "unchanged",
+    run,
+  };
+}
+
 async function waitForConversationRunPoll(
   ms: number,
   abortSignal?: AbortSignal,

package/src/src/agent/index.ts

@@ -219,6 +219,7 @@ export {
   AppendConversationRunEventsResponseSchema,
   CompleteConversationRunResponseSchema,
   type ConversationAgentRunUsage,
+  type ConversationRunAppendCursorResyncResult,
   type ConversationRunProjection,
   ConversationRunProjectionSchema,
   ConversationRunStatusSchema,
@@ -229,11 +230,13 @@ export {
   finalizeConversationAgentRun,
   getConversationRun,
   isActiveConversationRunStatus,
+  isAppendableConversationRunProjection,
   isCursorMismatchConversationRunAppendError,
   isIgnorableConversationRunAppendError,
   monitorConversationRunStatus,
   parseAppendConversationRunEventsErrorBody,
   resolveConversationRunTargets,
+  resyncConversationRunAppendCursor,
   type TerminalConversationRunStatus,
 } from "./durable.js";
 export {

package/src/src/oauth/handlers/callback-handler.ts

@@ -6,7 +6,7 @@ import {
 } from "../../config/environment-config.js";
 import { type EnvReader, OAuthService } from "../providers/base.js";
 import { memoryTokenStore } from "../token-store/memory.js";
-import type { OAuthServiceConfig, OAuthState, TokenStore } from "../types.js";
+import type { OAuthServiceConfig, StoredOAuthState, TokenStore } from "../types.js";
 
 const logger = baseLogger.component("o-auth");
 
@@ -23,8 +23,8 @@ export interface OAuthCallbackHandlerOptions {
   /** Error redirect path */
   errorRedirect?: string;
 
-  /** Custom success callback */
-  onSuccess?: (serviceId: string, tokens: unknown) => void | Promise<void>;
+  /** Custom success callback (called with the user id the tokens were stored under) */
+  onSuccess?: (serviceId: string, tokens: unknown, userId: string) => void | Promise<void>;
 
   /** Custom error callback */
   onError?: (serviceId: string, error: string) => void | Promise<void>;
@@ -102,7 +102,7 @@ export function createOAuthCallbackHandler(
 
     if (!code) return handleError(appUrl, "no_code");
 
-    let storedState: OAuthState | null = null;
+    let storedState: StoredOAuthState | null = null;
 
     if (!skipStateValidation && !state) {
       return handleError(appUrl, "invalid_state", "Missing state parameter", {
@@ -111,12 +111,20 @@ export function createOAuthCallbackHandler(
     }
 
     if (state) {
-      storedState = await tokenStore.getState(state);
+      // Atomic read+delete. Unknown/expired/forged state all return null.
+      storedState = await tokenStore.consumeState(state);
       if (!skipStateValidation && !storedState) {
         return handleError(appUrl, "invalid_state", "Invalid or expired state", {
           serviceId: config.serviceId,
         });
       }
+      // A state record from a different service must never authorize this one.
+      if (storedState && storedState.serviceId !== config.serviceId) {
+        return handleError(appUrl, "invalid_state", "State serviceId mismatch", {
+          serviceId: config.serviceId,
+          stateServiceId: storedState.serviceId,
+        });
+      }
     }
 
     const service = new OAuthService(config, tokenStore, envReader);
@@ -138,11 +146,20 @@ export function createOAuthCallbackHandler(
         );
       }
 
-      await tokenStore.setTokens(config.serviceId, result.tokens);
+      // Without state (skipStateValidation) we have no userId — refuse to
+      // store tokens under a shared slot. Callers who need this path must
+      // provide a store that handles it themselves (e.g. cookie-scoped).
+      if (!storedState) {
+        return handleError(
+          appUrl,
+          "invalid_state",
+          `Cannot store tokens for ${config.serviceId}: no state (and thus no userId) available`,
+        );
+      }
 
-      if (state) await tokenStore.clearState(state);
+      await tokenStore.setTokens(config.serviceId, storedState.userId, result.tokens);
 
-      await onSuccess?.(config.serviceId, result.tokens);
+      await onSuccess?.(config.serviceId, result.tokens, storedState.userId);
 
       const successUrl = new URL(successRedirect, appUrl);
       successUrl.searchParams.set("connected", config.serviceId);

package/src/src/oauth/handlers/init-handler.ts

@@ -22,6 +22,24 @@ async function isRequestUnauthorized(
   return isAuthenticated ? !(await isAuthenticated(req)) : false;
 }
 
+/**
+ * Resolve the userId for a request, returning null when anonymous.
+ *
+ * `getUserId` is required at compile time (see handler option types). We
+ * still tolerate `undefined` at runtime (e.g. a JS caller) and treat it as
+ * unauthenticated — NEVER fall back to "anonymous": that preserves
+ * VULN-AUTH-2 where unrelated users share a single token slot.
+ */
+async function resolveUserId(
+  req: Request,
+  getUserId: GetUserIdFn | undefined,
+): Promise<string | null> {
+  if (!getUserId) return null;
+  const result = await getUserId(req);
+  if (!result) return null; // null, undefined, or empty string all fail.
+  return result;
+}
+
 function resolveAppUrl(baseUrl: string | undefined, env: EnvironmentConfig): string {
   return baseUrl ?? env.appUrl ?? DEFAULT_APP_URL;
 }
@@ -46,6 +64,9 @@ function createInitErrorResponse(error: unknown): Response {
   );
 }
 
+/** Signature for resolving the authenticated user's id from a request. */
+export type GetUserIdFn = (req: Request) => string | null | Promise<string | null>;
+
 export interface OAuthInitHandlerOptions {
   /** Token store to use (defaults to memory store) */
   tokenStore?: TokenStore;
@@ -61,21 +82,45 @@ export interface OAuthInitHandlerOptions {
 
   /** EnvReader for dynamic env vars (defaults to getEnv) */
   envReader?: EnvReader;
+
+  /**
+   * Optional authentication check. If supplied and returns false the request
+   * is rejected with 401. Independent from `getUserId` which always runs.
+   */
+  isAuthenticated?: (req: Request) => boolean | Promise<boolean>;
+
+  /**
+   * REQUIRED. Resolve the authenticated user's id. The returned id is
+   * persisted with the OAuth `state` so the callback stores tokens in that
+   * user's slot. Return `null` (or an empty string) to reject unauthenticated
+   * requests with 401. NEVER return a shared constant like "anonymous" —
+   * that re-introduces VULN-AUTH-2.
+   */
+  getUserId: GetUserIdFn;
 }
 
 export function createOAuthInitHandler(
   config: OAuthServiceConfig,
-  options: OAuthInitHandlerOptions = {},
-): () => Promise<Response> {
+  options: OAuthInitHandlerOptions,
+): (req: Request) => Promise<Response> {
   const {
     tokenStore = memoryTokenStore,
     baseUrl,
     authOptions = {},
     env = getEnvironmentConfig(),
     envReader = getEnv,
-  } = options;
+    isAuthenticated,
+    getUserId,
+  } = options ?? ({} as OAuthInitHandlerOptions);
+
+  return async function handler(req: Request): Promise<Response> {
+    if (await isRequestUnauthorized(req, isAuthenticated)) {
+      return createUnauthorizedResponse();
+    }
+
+    const userId = await resolveUserId(req, getUserId);
+    if (!userId) return createUnauthorizedResponse();
 
-  return async function handler(): Promise<Response> {
     const service = new OAuthService(config, tokenStore, envReader);
 
     if (!service.isConfigured()) {
@@ -87,7 +132,15 @@ export function createOAuthInitHandler(
 
     try {
       const { url, state } = await service.createAuthorizationUrl({ ...authOptions, redirectUri });
-      await tokenStore.setState(state);
+      await tokenStore.setState(state.state, {
+        userId,
+        serviceId: config.serviceId,
+        codeVerifier: state.codeVerifier,
+        redirectUri: state.redirectUri,
+        scopes: state.scopes,
+        createdAt: state.createdAt,
+        metadata: state.metadata,
+      });
       return Response.redirect(url);
     } catch (error) {
       logger.error("Init error", { serviceId: config.serviceId }, error);
@@ -105,24 +158,31 @@ export interface OAuthStatusHandlerOptions {
 
   /** Optional authentication check — return true if the request is authenticated */
   isAuthenticated?: (req: Request) => boolean | Promise<boolean>;
+
+  /** REQUIRED. Resolve the authenticated user's id (see OAuthInitHandlerOptions). */
+  getUserId: GetUserIdFn;
 }
 
 export function createOAuthStatusHandler(
   config: OAuthServiceConfig,
-  options: OAuthStatusHandlerOptions = {},
+  options: OAuthStatusHandlerOptions,
 ): (req: Request) => Promise<Response> {
   const {
     tokenStore = memoryTokenStore,
     envReader = getEnv,
     isAuthenticated,
-  } = options;
+    getUserId,
+  } = options ?? ({} as OAuthStatusHandlerOptions);
 
   return async function handler(req: Request): Promise<Response> {
     if (await isRequestUnauthorized(req, isAuthenticated)) {
       return createUnauthorizedResponse();
     }
 
-    const tokens = await tokenStore.getTokens(config.serviceId);
+    const userId = await resolveUserId(req, getUserId);
+    if (!userId) return createUnauthorizedResponse();
+
+    const tokens = await tokenStore.getTokens(config.serviceId, userId);
 
     const isConnected = !!tokens?.accessToken;
     const isExpired = tokens?.expiresAt ? Date.now() > tokens.expiresAt : false;
@@ -139,22 +199,30 @@ export function createOAuthStatusHandler(
   };
 }
 
+export interface OAuthDisconnectHandlerOptions {
+  tokenStore?: TokenStore;
+  /** Optional authentication check — return true if the request is authenticated */
+  isAuthenticated?: (req: Request) => boolean | Promise<boolean>;
+  /** REQUIRED. Resolve the authenticated user's id (see OAuthInitHandlerOptions). */
+  getUserId: GetUserIdFn;
+}
+
 export function createOAuthDisconnectHandler(
   config: OAuthServiceConfig,
-  options: {
-    tokenStore?: TokenStore;
-    /** Optional authentication check — return true if the request is authenticated */
-    isAuthenticated?: (req: Request) => boolean | Promise<boolean>;
-  } = {},
+  options: OAuthDisconnectHandlerOptions,
 ): (req: Request) => Promise<Response> {
-  const { tokenStore = memoryTokenStore, isAuthenticated } = options;
+  const { tokenStore = memoryTokenStore, isAuthenticated, getUserId } = options ??
+    ({} as OAuthDisconnectHandlerOptions);
 
   return async function handler(req: Request): Promise<Response> {
     if (await isRequestUnauthorized(req, isAuthenticated)) {
       return createUnauthorizedResponse();
     }
 
-    await tokenStore.clearTokens(config.serviceId);
+    const userId = await resolveUserId(req, getUserId);
+    if (!userId) return createUnauthorizedResponse();
+
+    await tokenStore.clearTokens(config.serviceId, userId);
 
     return Response.json({
       success: true,

package/src/src/oauth/providers/base.ts

@@ -315,8 +315,15 @@ export class OAuthService extends OAuthProvider {
     });
   }
 
-  async getAccessToken(): Promise<string | null> {
-    const tokens = await this.tokenStore?.getTokens(this.serviceId);
+  /**
+   * Get a valid access token for the given user, refreshing if needed.
+   *
+   * `userId` is required — this store is keyed by `(serviceId, userId)` to
+   * prevent one user's OAuth completion from overwriting another user's
+   * tokens. See VULN-AUTH-2.
+   */
+  async getAccessToken(userId: string): Promise<string | null> {
+    const tokens = await this.tokenStore?.getTokens(this.serviceId, userId);
     if (!tokens) return null;
 
     const isExpired = tokens.expiresAt && Date.now() > tokens.expiresAt - TOKEN_REFRESH_BUFFER_MS;
@@ -330,12 +337,12 @@ export class OAuthService extends OAuthProvider {
     if (!this.tokenStore) {
       throw new Error("TokenStore not configured");
     }
-    await this.tokenStore.setTokens(this.serviceId, result.tokens);
+    await this.tokenStore.setTokens(this.serviceId, userId, result.tokens);
     return result.tokens.accessToken;
   }
 
-  async fetch<T>(endpoint: string, options: RequestInit = {}): Promise<T> {
-    const token = await this.getAccessToken();
+  async fetch<T>(userId: string, endpoint: string, options: RequestInit = {}): Promise<T> {
+    const token = await this.getAccessToken(userId);
     if (!token) {
       throw TOKEN_STORAGE_ERROR.create({
         detail: `Not authenticated with ${this.serviceConfig.displayName}`,

package/src/src/oauth/token-store/index.ts

@@ -5,4 +5,4 @@
  */
 
 export { MemoryTokenStore, memoryTokenStore } from "./memory.js";
-export type { OAuthState, OAuthTokens, TokenStore } from "../types.js";
+export type { OAuthState, OAuthTokens, StoredOAuthState, TokenStore } from "../types.js";

package/src/src/oauth/token-store/memory.ts

@@ -1,69 +1,82 @@
-import type { OAuthState, OAuthTokens, TokenStore } from "../types.js";
-
-/** How long an OAuth state nonce remains valid (10 minutes). */
-const STATE_EXPIRATION_MS = 10 * 60 * 1_000;
-
+import type { OAuthTokens, StoredOAuthState, TokenStore } from "../types.js";
+
+/** State expiry window: reject any state older than this (10 minutes). */
+const STATE_EXPIRY_MS = 10 * 60 * 1_000;
+
+/**
+ * In-memory TokenStore keyed by `(serviceId, userId)`.
+ *
+ * Suitable for development and tests. For production use a persistent store
+ * (Redis, Postgres, ...) keyed the same way. Never share a single slot per
+ * service across users — see VULN-AUTH-2.
+ */
 export class MemoryTokenStore implements TokenStore {
   private tokens = new Map<string, OAuthTokens>();
-  private states = new Map<string, OAuthState>();
+  private states = new Map<string, StoredOAuthState>();
   private projectId: string;
 
   constructor(projectId = "default") {
     this.projectId = projectId;
   }
 
-  private scopedKey(serviceId: string): string {
-    return `${this.projectId}:${serviceId}`;
-  }
-
-  async getTokens(serviceId: string): Promise<OAuthTokens | null> {
-    return this.tokens.get(this.scopedKey(serviceId)) ?? null;
+  private scopedKey(serviceId: string, userId: string): string {
+    return `${this.projectId}:${serviceId}:${userId}`;
   }
 
-  async setTokens(serviceId: string, tokens: OAuthTokens): Promise<void> {
-    this.tokens.set(this.scopedKey(serviceId), tokens);
+  getTokens(serviceId: string, userId: string): Promise<OAuthTokens | null> {
+    return Promise.resolve(this.tokens.get(this.scopedKey(serviceId, userId)) ?? null);
   }
 
-  async clearTokens(serviceId: string): Promise<void> {
-    this.tokens.delete(this.scopedKey(serviceId));
+  setTokens(serviceId: string, userId: string, tokens: OAuthTokens): Promise<void> {
+    this.tokens.set(this.scopedKey(serviceId, userId), tokens);
+    return Promise.resolve();
   }
 
-  async getState(state: string): Promise<OAuthState | null> {
-    const storedState = this.states.get(state);
-    if (!storedState) return null;
-
-    if (Date.now() - storedState.createdAt > STATE_EXPIRATION_MS) {
-      this.states.delete(state);
-      return null;
-    }
-
-    return storedState;
+  clearTokens(serviceId: string, userId: string): Promise<void> {
+    this.tokens.delete(this.scopedKey(serviceId, userId));
+    return Promise.resolve();
   }
 
-  async setState(storedState: OAuthState): Promise<void> {
-    this.states.set(storedState.state, storedState);
+  setState(state: string, meta: StoredOAuthState): Promise<void> {
+    this.states.set(state, meta);
     this.cleanupExpiredStates();
+    return Promise.resolve();
   }
 
-  async clearState(state: string): Promise<void> {
+  /**
+   * Atomically read and delete state (one-shot). Returns null for unknown or
+   * expired entries. Expired entries are removed on read.
+   */
+  consumeState(state: string): Promise<StoredOAuthState | null> {
+    const meta = this.states.get(state);
+    if (!meta) return Promise.resolve(null);
     this.states.delete(state);
+    if (Date.now() - meta.createdAt > STATE_EXPIRY_MS) {
+      return Promise.resolve(null);
+    }
+    return Promise.resolve(meta);
   }
 
   private cleanupExpiredStates(): void {
     const now = Date.now();
-    for (const [state, storedState] of this.states) {
-      if (now - storedState.createdAt > STATE_EXPIRATION_MS) {
+    for (const [state, meta] of this.states) {
+      if (now - meta.createdAt > STATE_EXPIRY_MS) {
         this.states.delete(state);
       }
     }
   }
 
+  /** List connected slots as `${serviceId}:${userId}` strings (test/debug aid). */
   getConnectedServices(): string[] {
-    return [...this.tokens.keys()];
+    const prefix = `${this.projectId}:`;
+    return [...this.tokens.keys()].map((key) =>
+      key.startsWith(prefix) ? key.slice(prefix.length) : key
+    );
   }
 
-  isConnected(serviceId: string): boolean {
-    const tokens = this.tokens.get(this.scopedKey(serviceId));
+  /** Whether a given user has usable tokens for a service. */
+  isConnected(serviceId: string, userId: string): boolean {
+    const tokens = this.tokens.get(this.scopedKey(serviceId, userId));
     if (!tokens) return false;
 
     const isExpired = tokens.expiresAt != null && Date.now() > tokens.expiresAt;
@@ -76,4 +89,4 @@ export class MemoryTokenStore implements TokenStore {
   }
 }
 
-export const memoryTokenStore = new MemoryTokenStore();
+export const memoryTokenStore: TokenStore = new MemoryTokenStore();

package/src/src/oauth/types.ts

@@ -10,13 +10,40 @@ export type {
 } from "./schemas/index.js";
 
 // Import types used locally in this file
-import type { OAuthState, OAuthTokens } from "./schemas/index.js";
+import type { OAuthTokens } from "./schemas/index.js";
 
+/**
+ * Persisted OAuth state row. Created when init handler starts a flow and
+ * consumed exactly once by the callback handler.
+ *
+ * `userId` binds the flow to the authenticated user who initiated it so the
+ * resulting tokens are stored in that user's slot (not a shared one).
+ */
+export interface StoredOAuthState {
+  userId: string;
+  serviceId: string;
+  codeVerifier?: string;
+  redirectUri?: string;
+  scopes?: string[];
+  createdAt: number;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * TokenStore is keyed by `(serviceId, userId)` — tokens are per-user.
+ *
+ * Using a single-slot-per-service store is a vulnerability: the last OAuth
+ * completion overwrites all others, so an attacker who starts and finishes
+ * an OAuth flow with their own account can cause server-side code to act
+ * on the attacker's account. Callers MUST pass `userId` from authenticated
+ * session context.
+ */
 export interface TokenStore {
-  getTokens(serviceId: string): Promise<OAuthTokens | null>;
-  setTokens(serviceId: string, tokens: OAuthTokens): Promise<void>;
-  clearTokens(serviceId: string): Promise<void>;
-  getState(state: string): Promise<OAuthState | null>;
-  setState(state: OAuthState): Promise<void>;
-  clearState(state: string): Promise<void>;
+  getTokens(serviceId: string, userId: string): Promise<OAuthTokens | null>;
+  setTokens(serviceId: string, userId: string, tokens: OAuthTokens): Promise<void>;
+  clearTokens(serviceId: string, userId: string): Promise<void>;
+  /** Persist a new OAuth state row for the initiating user. */
+  setState(state: string, meta: StoredOAuthState): Promise<void>;
+  /** Atomically read and delete state. Returns null if unknown/expired. */
+  consumeState(state: string): Promise<StoredOAuthState | null>;
 }

package/src/src/platform/compat/framework-source-resolver.ts

@@ -1,8 +1,31 @@
 import { join } from "./path/index.js";
 import type { FileInfo } from "../adapters/base.js";
+import { isWithinDirectory } from "../../security/path-validation.js";
 import { createFileSystem } from "./fs.js";
 import { getFrameworkRoot, getFrameworkRootFromMeta } from "./vfs-paths.js";
 
+/**
+ * Reject candidate paths that contain traversal indicators — plain `..`,
+ * NUL, or any percent-encoded variant (including multiply-encoded forms such
+ * as `%252e` or `%25252e`). The public `/_vf_modules/...` route reaches this
+ * resolver, so a malicious basePath like
+ * `_veryfront/%2e%2e%2fsecret.ts` would otherwise be joined with the
+ * framework lookupDir and escape it.
+ */
+function hasDangerousSegments(candidate: string): boolean {
+  if (candidate.includes("\0")) return true;
+  // Plain-text traversal (post URL-decode).
+  if (/(^|[/\\])\.\.([/\\]|$)/.test(candidate)) return true;
+  // Any occurrence of a percent sign is treated as suspicious: this resolver
+  // is called with inputs taken from URL path segments which have already
+  // been decoded once upstream. A lingering `%` means the attacker
+  // double-encoded the input, or that decoding missed a sequence — either
+  // way, refuse to probe the filesystem. Framework source paths never
+  // legitimately contain `%`.
+  if (candidate.includes("%")) return true;
+  return false;
+}
+
 export const FRAMEWORK_ROOT = getFrameworkRootFromMeta(import.meta.url);
 export const FRAMEWORK_SRC_DIR = join(FRAMEWORK_ROOT, "src");
 export const FRAMEWORK_EMBEDDED_SRC_DIR = join(FRAMEWORK_ROOT, "dist", "framework-src");
@@ -105,6 +128,11 @@ export async function resolveFrameworkSourcePath(
   relativePathWithoutExt: string,
   options: ResolveFrameworkSourcePathOptions = {},
 ): Promise<FrameworkSourceLookupResult | null> {
+  // VULN-FS-3: Reject any candidate containing traversal indicators
+  // (plain or percent-encoded) before joining with the framework lookup dir.
+  // The public /_vf_modules/... route reaches this function with user input.
+  if (hasDangerousSegments(relativePathWithoutExt)) return null;
+
   const fs = options.fileSystem ?? createFileSystem();
   const lookupDirs = getFrameworkSourceLookupDirs(options.extraLookupDirs);
   const extensions = options.extensions ?? DEFAULT_FRAMEWORK_SOURCE_EXTENSIONS;
@@ -119,6 +147,10 @@ export async function resolveFrameworkSourcePath(
       for (const ext of extensions) {
         const candidatePath = join(lookupDir, candidate + ext);
 
+        // Defence in depth: even if the candidate passed the textual gate
+        // above, confirm the joined path is physically within the lookup dir.
+        if (!isWithinDirectory(lookupDir, candidatePath)) continue;
+
         try {
           const stat = await fs.stat(candidatePath);
           if (stat.isFile) {