fix(kap-server): close auth bypass via percent-encoded API paths (#1753)

* fix(kap-server): fail closed on percent-encoded API paths in auth bypass

The auth hook checked the raw, still percent-encoded request URL against
its bypass policy, while find-my-way matches routes against the decoded
path. A raw /%61pi/v1/... URL therefore skipped the bearer-token check
yet still reached the /api/... handlers, allowing unauthenticated access
to every API route.

Decode the request path the same way the router does before matching,
and fail closed when the path cannot be decoded. Add tests covering
encoded /api/ paths, encoded meta documents, the encoded healthz probe,
and unaffected non-API bypasses.

* fix(agent-core-v2): make session fs path confinement symlink-aware

SessionFsService confined paths only lexically, so a symlink planted
inside the workspace could steer read, list, stat, mkdir, resolvePath
and resolveDownload to host files outside the session directory.

- add IHostFileSystem.realpath (Node fs.realpath semantics) and
  implement it in the node-local HostFileSystem
- resolveWithin now re-verifies each candidate through realpath of the
  longest existing prefix (so not-yet-created paths still work) and
  rejects paths escaping the canonicalized workspace roots, which are
  resolved once and cached
- cover symlink escapes for every fs entry point plus kap-server
  read/download e2e; in-workspace symlink targets remain allowed

* fix(agent-core-v2): accept workspace roots given through a symlink

WorkspaceRegistryService.createOrTouch probes the root with the
lstat-based IHostFileSystem.stat, so a root given as a symlink to a
directory reported isDirectory=false and session creation was rejected
with fs.path_not_found ("not a directory").

Re-check a non-directory root through IHostFileSystem.realpath before
failing, while keeping the workspace identity lexical (v1 deliberately
never realpaths the root either). Covered by a unit test for a
symlink-form root and a kap-server e2e that creates a session with a
symlinked cwd and reads a file through it.

Author: sailist

.changeset/fix-kap-server-auth-encoded-path.md

@@ -0,0 +1,5 @@
+---
+"@moonshot-ai/kimi-code": patch
+---
+
+Fix the web server bearer-token check being bypassed by percent-encoded API paths (e.g. `/%61pi/v1/…`), which allowed unauthenticated access to every API route.

.changeset/fix-sessionfs-symlink-escape.md

@@ -0,0 +1,5 @@
+---
+"@moonshot-ai/kimi-code": patch
+---
+
+Fix the session filesystem API following symlinks that point outside the workspace, which allowed reading, listing, creating, and downloading host files beyond the session directory through a planted symlink.

.changeset/fix-symlinked-workspace-root.md

@@ -0,0 +1,5 @@
+---
+"@moonshot-ai/kimi-code": patch
+---
+
+Fix sessions failing to be created when the workspace directory is given through a symlink, which the v2 engine rejected as "not a directory".

packages/agent-core-v2/src/app/workspaceRegistry/workspaceRegistryService.ts

@@ -31,9 +31,12 @@
  * `createOrTouch` is the single choke point every workspace/session creation
  * funnels through, so it owns the root-existence contract: the root must be
  * an existing directory on the host filesystem, otherwise it throws
- * `fs.path_not_found` (mirrors v1's `WorkspaceRootNotFoundError`). The rebuild
- * and merge paths bypass the check on purpose — they catalog where sessions
- * *were*, not where new ones may open. Bound at App scope.
+ * `fs.path_not_found` (mirrors v1's `WorkspaceRootNotFoundError`). The
+ * directory probe follows symlinks (`IHostFileSystem.stat` is lstat-based, so
+ * a symlink-form root is re-checked through `realpath`), while the workspace
+ * identity stays lexical — v1 deliberately never realpaths the root either.
+ * The rebuild and merge paths bypass the check on purpose — they catalog
+ * where sessions *were*, not where new ones may open. Bound at App scope.
  */
 
 import { basename, isAbsolute } from 'pathe';
@@ -101,6 +104,13 @@ export class WorkspaceRegistryService implements IWorkspaceRegistry {
         }
         throw error;
       }
+      if (!stat.isDirectory) {
+        try {
+          stat = await this.hostFs.stat(await this.hostFs.realpath(root));
+        } catch {
+          // Fall through to the not-a-directory error below.
+        }
+      }
       if (!stat.isDirectory) {
         throw new Error2(ErrorCodes.FS_PATH_NOT_FOUND, `workspace root ${root} is not a directory`);
       }

packages/agent-core-v2/src/os/backends/node-local/hostFsService.ts

@@ -5,7 +5,17 @@
  * Bound at App scope.
  */
 
-import { appendFile, lstat, open, readFile, readdir, mkdir, rm, writeFile } from 'node:fs/promises';
+import {
+  appendFile,
+  lstat,
+  open,
+  readFile,
+  readdir,
+  mkdir,
+  realpath as nodeRealpath,
+  rm,
+  writeFile,
+} from 'node:fs/promises';
 
 import { InstantiationType } from '#/_base/di/extensions';
 import { LifecycleScope, registerScopedService } from '#/_base/di/scope';
@@ -222,6 +232,14 @@ export class HostFileSystem implements IHostFileSystem {
       throw toHostFsError(error, { path, op: 'remove' });
     }
   }
+
+  async realpath(path: string): Promise<string> {
+    try {
+      return await nodeRealpath(path);
+    } catch (error) {
+      throw toHostFsError(error, { path, op: 'realpath' });
+    }
+  }
 }
 
 registerScopedService(

packages/agent-core-v2/src/os/interface/hostFileSystem.ts

@@ -3,8 +3,10 @@
  *
  * Defines the `IHostFileSystem` used by the program side (persistence, skill
  * loading, workspace registry) and the os file tools to read and write files on
- * the real local disk, plus the stat/entry models. App-scoped — one shared
- * instance.
+ * the real local disk, plus the stat/entry models. `realpath` canonicalizes a
+ * path by resolving every symlink component (Node `fs.realpath` semantics) and
+ * rejects with `os.fs.not_found` for a missing path; consumers use it to make
+ * lexical path confinement symlink-aware. App-scoped — one shared instance.
  */
 
 import { createDecorator, type ServiceIdentifier } from '#/_base/di/instantiation';
@@ -46,6 +48,7 @@ export interface IHostFileSystem {
   readdir(path: string): Promise<readonly HostDirEntry[]>;
   mkdir(path: string, options?: { readonly recursive?: boolean }): Promise<void>;
   remove(path: string): Promise<void>;
+  realpath(path: string): Promise<string>;
 }
 
 export const IHostFileSystem: ServiceIdentifier<IHostFileSystem> =

packages/agent-core-v2/src/session/sessionFs/fsService.ts

@@ -9,11 +9,13 @@
  * `IGitService`; this service only confines paths and computes repo-relative
  * paths before calling it.
  *
- * Path confinement is lexical (`ISessionWorkspaceContext.isWithin`); it does not
- * follow symlinks, matching the rest of v2 (`_base/tools/policies/path-access.ts`).
+ * Path confinement applies the lexical `ISessionWorkspaceContext.isWithin`
+ * check first, then re-verifies the candidate through `IHostFileSystem.realpath`
+ * (resolving the longest existing prefix, so not-yet-created paths still work):
+ * a symlink inside the workspace must not steer fs actions to files outside it.
  */
 
-import { basename, extname, isAbsolute, join, relative, sep } from 'node:path';
+import { basename, dirname, extname, isAbsolute, join, relative, sep } from 'node:path';
 
 import {
   type FsDiffRequest,
@@ -60,7 +62,7 @@ import ignore, { type Ignore } from 'ignore';
 
 import { InstantiationType } from '#/_base/di/extensions';
 import { LifecycleScope, registerScopedService } from '#/_base/di/scope';
-import { ErrorCodes, Error2, unwrapErrorCause } from '#/errors';
+import { ErrorCodes, Error2, isError2, unwrapErrorCause } from '#/errors';
 import { IGitService } from '#/app/git/git';
 import { ITelemetryService } from '#/app/telemetry/telemetry';
 import { IHostFileSystem, type HostDirEntry, type HostFileStat } from '#/os/interface/hostFileSystem';
@@ -111,7 +113,7 @@ export class SessionFsService implements ISessionFsService {
   }
 
   async list(req: FsListRequest): Promise<FsListResponse> {
-    const abs = this.resolveWithin(req.path);
+    const abs = await this.resolveWithin(req.path);
     const rel = this.toRel(abs);
 
     let topStat: HostFileStat;
@@ -203,7 +205,7 @@ export class SessionFsService implements ISessionFsService {
   }
 
   async read(req: FsReadRequest): Promise<FsReadResponse> {
-    const abs = this.resolveWithin(req.path);
+    const abs = await this.resolveWithin(req.path);
     const rel = this.toRel(abs);
 
     let st: HostFileStat;
@@ -303,7 +305,7 @@ export class SessionFsService implements ISessionFsService {
   }
 
   async stat(req: FsStatRequest): Promise<FsStatResponse> {
-    const abs = this.resolveWithin(req.path);
+    const abs = await this.resolveWithin(req.path);
     const rel = this.toRel(abs);
     let st: HostFileStat;
     try {
@@ -316,10 +318,12 @@ export class SessionFsService implements ISessionFsService {
   }
 
   async statMany(req: FsStatManyRequest): Promise<FsStatManyResponse> {
-    const resolved = req.paths.map((p) => {
-      const abs = this.resolveWithin(p);
-      return { raw: p, rel: this.toRel(abs), abs };
-    });
+    const resolved = await Promise.all(
+      req.paths.map(async (p) => {
+        const abs = await this.resolveWithin(p);
+        return { raw: p, rel: this.toRel(abs), abs };
+      }),
+    );
 
     const entries: Record<string, FsEntry | null> = {};
     await Promise.all(
@@ -337,7 +341,7 @@ export class SessionFsService implements ISessionFsService {
   }
 
   async mkdir(req: FsMkdirRequest): Promise<FsMkdirResponse> {
-    const abs = this.resolveWithin(req.path);
+    const abs = await this.resolveWithin(req.path);
     const rel = this.toRel(abs);
     try {
       await this.hostFs.mkdir(abs, { recursive: req.recursive });
@@ -360,7 +364,7 @@ export class SessionFsService implements ISessionFsService {
   }
 
   async resolvePath(relPath: string): Promise<FsPathResolved> {
-    const abs = this.resolveWithin(relPath);
+    const abs = await this.resolveWithin(relPath);
     const rel = this.toRel(abs);
     let st: HostFileStat;
     try {
@@ -372,7 +376,7 @@ export class SessionFsService implements ISessionFsService {
   }
 
   async resolveDownload(relPath: string): Promise<FsDownloadResolved> {
-    const abs = this.resolveWithin(relPath);
+    const abs = await this.resolveWithin(relPath);
     const rel = this.toRel(abs);
     let st: HostFileStat;
     try {
@@ -456,7 +460,7 @@ export class SessionFsService implements ISessionFsService {
     if (req.paths !== undefined && req.paths.length > 0) {
       filter = new Set();
       for (const p of req.paths) {
-        filter.add(this.toRel(this.resolveWithin(p)));
+        filter.add(this.toRel(await this.resolveWithin(p)));
       }
     }
 
@@ -465,7 +469,7 @@ export class SessionFsService implements ISessionFsService {
 
   async diff(req: FsDiffRequest): Promise<FsDiffResponse> {
     const cwd = this.workspace.workDir;
-    const abs = this.resolveWithin(req.path);
+    const abs = await this.resolveWithin(req.path);
     return this.git.diff(cwd, this.toRel(abs), abs);
   }
 
@@ -683,7 +687,43 @@ export class SessionFsService implements ISessionFsService {
     return this.rgResolution;
   }
 
-  private resolveWithin(inputPath: string): string {
+  private realRootsCache: { readonly key: string; readonly roots: readonly string[] } | undefined;
+
+  private async realRoots(): Promise<readonly string[]> {
+    const dirs = [this.workspace.workDir, ...this.workspace.additionalDirs];
+    const key = dirs.join('\n');
+    if (this.realRootsCache?.key === key) return this.realRootsCache.roots;
+    const roots: string[] = [];
+    for (const dir of dirs) {
+      try {
+        roots.push(await this.hostFs.realpath(dir));
+      } catch {
+        roots.push(dir);
+      }
+    }
+    this.realRootsCache = { key, roots };
+    return roots;
+  }
+
+  private async realpathExistingPrefix(abs: string): Promise<string> {
+    const tail: string[] = [];
+    let current = abs;
+    for (let i = 0; i < 256; i++) {
+      try {
+        const real = await this.hostFs.realpath(current);
+        return tail.length === 0 ? real : join(real, ...tail.reverse());
+      } catch (err) {
+        if (!isMissingPathError(err)) throw err;
+        const parent = dirname(current);
+        if (parent === current) return abs;
+        tail.push(basename(current));
+        current = parent;
+      }
+    }
+    return abs;
+  }
+
+  private async resolveWithin(inputPath: string): Promise<string> {
     if (inputPath === '' || inputPath === '/') {
       throw new Error2(ErrorCodes.FS_PATH_ESCAPES, `path "${inputPath}" rejected (empty)`, {
         details: { path: inputPath, reason: 'empty' },
@@ -706,6 +746,15 @@ export class SessionFsService implements ISessionFsService {
         details: { path: inputPath, reason: 'resolved_outside' },
       });
     }
+    const resolved = await this.realpathExistingPrefix(abs);
+    const roots = await this.realRoots();
+    if (!roots.some((root) => isInsideOrEqual(resolved, root))) {
+      throw new Error2(
+        ErrorCodes.FS_PATH_ESCAPES,
+        `path "${inputPath}" escapes workspace through a symlink`,
+        { details: { path: inputPath, reason: 'symlink_outside' } },
+      );
+    }
     return abs;
   }
 
@@ -919,6 +968,24 @@ function errnoCode(err: unknown): string | undefined {
   return undefined;
 }
 
+function isMissingPathError(err: unknown): boolean {
+  if (isError2(err)) {
+    return (
+      err.code === ErrorCodes.OS_FS_NOT_FOUND || err.code === ErrorCodes.OS_FS_NOT_DIRECTORY
+    );
+  }
+  const code = errnoCode(err);
+  return code === 'ENOENT' || code === 'ENOTDIR';
+}
+
+function isInsideOrEqual(child: string, parent: string): boolean {
+  const rel = relative(parent, child);
+  if (rel === '') return true;
+  if (rel.startsWith('..')) return false;
+  if (isAbsolute(rel)) return false;
+  return true;
+}
+
 function mapFsError(err: unknown, inputPath: string): Error {
   const code = errnoCode(err);
   if (code === 'ENOENT' || code === 'ENOTDIR') {

packages/agent-core-v2/test/app/workspaceRegistry/workspaceRegistryService.test.ts

@@ -382,6 +382,16 @@ describe('WorkspaceRegistryService (file-backed)', () => {
     expect(await build().list()).toEqual([]);
   });
 
+  it('accepts createOrTouch when the root is given through a symlink', async () => {
+    const real = join(homeDir, 'real-root');
+    await fsp.mkdir(real, { recursive: true });
+    const link = join(homeDir, 'link-root');
+    await fsp.symlink(real, link, 'dir');
+    const ws = await build().createOrTouch(link);
+    expect(ws.root).toBe(link);
+    expect(ws.id).toBe(encodeWorkDirKey(link));
+  });
+
   it('rejects createOrTouch when a parent of the root is not a directory', async () => {
     const file = join(homeDir, 'a-file.txt');
     await fsp.writeFile(file, 'hi', 'utf8');

packages/agent-core-v2/test/os/backends/node-local/tools/grep.test.ts

@@ -142,6 +142,7 @@ function createTestFs(kaos: FakeKaos): IHostFileSystem {
     readdir: () => notImplemented('readdir'),
     mkdir: () => notImplemented('mkdir'),
     remove: () => notImplemented('remove'),
+    realpath: () => notImplemented('realpath'),
   };
 }