@bevel-software/platform-core-backend 0.19.0 → 0.20.0

package/src/modules/tool-auth/external-api-key.service.ts

@@ -144,14 +144,25 @@ export class ExternalApiKeyService implements IExternalApiKeyService {
   }
 
   async listForUser(userId: string): Promise<ExternalApiKeySummary[]> {
+    // A key the owner deleted for good is gone from THEIR listings — that is
+    // what the deletion means to them; the row lives on for the Audit log.
     const rows = await this.db
       .select()
       .from(externalApiKeys)
-      .where(eq(externalApiKeys.userId, userId))
+      .where(and(eq(externalApiKeys.userId, userId), isNull(externalApiKeys.deletedAt)))
       .orderBy(desc(externalApiKeys.createdAt));
     return rows.map(toSummary);
   }
 
+  async ownerOf(id: string): Promise<string | null> {
+    const [row] = await this.db
+      .select({ userId: externalApiKeys.userId })
+      .from(externalApiKeys)
+      .where(eq(externalApiKeys.id, id))
+      .limit(1);
+    return row?.userId ?? null;
+  }
+
   async listForDeployment(): Promise<AdminExternalApiKeySummary[]> {
     // Owner joined in so the admin overview is one round-trip; ordered by
     // owner email so per-account grouping is a linear pass, newest key
@@ -219,14 +230,16 @@ export class ExternalApiKeyService implements IExternalApiKeyService {
   }
 
   async remove(id: string, userId: string): Promise<void> {
-    // Only revoked rows may be hard-deleted — deleting an active key would
+    // Only revoked rows may be deleted — deleting an active key would
     // silently cut off a live agent. Scope by userId so a user can only
     // delete their own tokens. Validate first (so we can return a precise
-    // not-found vs still-active error), then delete inside a transaction.
+    // not-found vs still-active error), then mark the row deleted.
     const [existing] = await this.db
       .select({ revokedAt: externalApiKeys.revokedAt })
       .from(externalApiKeys)
-      .where(and(eq(externalApiKeys.id, id), eq(externalApiKeys.userId, userId)))
+      .where(
+        and(eq(externalApiKeys.id, id), eq(externalApiKeys.userId, userId), isNull(externalApiKeys.deletedAt)),
+      )
       .limit(1);
     if (!existing) {
       throw new TokenNotFoundError();
@@ -236,16 +249,19 @@ export class ExternalApiKeyService implements IExternalApiKeyService {
       throw new TokenStillActiveError();
     }
 
-    // Dependents (e.g. the enterprise LLM-usage metering rows) hang off this
-    // row via ON DELETE CASCADE foreign keys, so a bare delete takes any audit
-    // trail with it — this service doesn't have to know those tables exist.
+    // A deletion in name: the row stays, marked, because the Audit log's
+    // events hang off it and the trail must outlive the key's owner's wish
+    // to be rid of it. The key was revoked already, so nothing can use it;
+    // deleting hides it from the owner and tells an admin it was deleted.
     await this.db
-      .delete(externalApiKeys)
+      .update(externalApiKeys)
+      .set({ deletedAt: new Date() })
       .where(
         and(
           eq(externalApiKeys.id, id),
           eq(externalApiKeys.userId, userId),
           isNotNull(externalApiKeys.revokedAt),
+          isNull(externalApiKeys.deletedAt),
         ),
       );
   }
@@ -271,5 +287,6 @@ function toSummary(row: typeof externalApiKeys.$inferSelect): ExternalApiKeySumm
     lastUsedAt: row.lastUsedAt ? row.lastUsedAt.getTime() : null,
     revokedAt: row.revokedAt ? row.revokedAt.getTime() : null,
     revokedBy: (row.revokedBy as RevokedBy | null) ?? null,
+    deletedAt: row.deletedAt ? row.deletedAt.getTime() : null,
   };
 }

package/src/modules/tool-auth/internal-token.service.ts

@@ -37,6 +37,16 @@ export interface InternalTokenClaim {
    * expected to carry `sessionId` on the tool body, not in the token.
    */
   externalProxy?: boolean;
+  /**
+   * The agent connection (`agent_connections.id`) an external-proxy token
+   * stands in for. The LOCAL MCP server swaps its OAuth grant for one of these
+   * at `/api/mcp/local-token` and presents it everywhere the grant would have
+   * gone, so without this claim every call it makes would arrive with a user
+   * and no agent — unattributable in the Audit log. Carried, never decided:
+   * the exchange copies it from the verified grant. Absent on every other
+   * internal token.
+   */
+  connectionId?: string;
 }
 
 interface SignedPayload extends InternalTokenClaim {
@@ -137,6 +147,7 @@ export class InternalTokenService {
       ...(typeof payload.sessionId === 'string' ? { sessionId: payload.sessionId } : {}),
       ...(typeof payload.focusedBranch === 'string' ? { focusedBranch: payload.focusedBranch } : {}),
       ...(payload.externalProxy === true ? { externalProxy: true } : {}),
+      ...(typeof payload.connectionId === 'string' ? { connectionId: payload.connectionId } : {}),
     };
   }
 

package/src/modules/tool-auth/tool-auth.middleware.ts

@@ -34,6 +34,14 @@ export interface ToolAuth {
    * never carries it and must name the branch explicitly.
    */
   focusedBranch?: string;
+  /**
+   * The agent connection an `externalProxy` token stands in for — the local
+   * server's exchanged grant names one (see `InternalTokenClaim.connectionId`).
+   * Only that grant carries it: the hosted proxy's own loopback tokens do
+   * not, and a connection key has a `tokenId` instead. What the REST audit
+   * recorder attributes a direct tool call to.
+   */
+  connectionId?: string;
   /** Always `'write'` now (the middleware sets it for both internal + external — neither credential carries scope). The read path is dormant until consumer agents are removed. */
   scope: 'read' | 'write';
 }
@@ -129,7 +137,15 @@ export function createTokenVerifier(
       const claim = internalTokenService.verify(token);
       if (!claim) return { ok: false, status: 401, message: 'Invalid or expired internal token' };
       return claim.externalProxy
-        ? { ok: true, auth: { source: 'external', userId: claim.userId, scope: 'write' } }
+        ? {
+            ok: true,
+            auth: {
+              source: 'external',
+              userId: claim.userId,
+              ...(claim.connectionId ? { connectionId: claim.connectionId } : {}),
+              scope: 'write',
+            },
+          }
         : { ok: true, auth: { source: 'internal', userId: claim.userId, sessionId: claim.sessionId, focusedBranch: claim.focusedBranch, scope: 'write' } };
     }
 

package/src/modules/workspace/__tests__/git-internals.security.test.ts

@@ -59,15 +59,50 @@ function fileForms(name: string): Record<string, string> {
     'leading slash': `/${KB}/.git/${name}`,
     dotted: `${KB}/Notes/../.git/${name}`,
     'dot segments': `./${KB}/./.git/${name}`,
+    // The five families production measured answering the path rule's 400
+    // instead of this rule's 403 (parent-climb, dot-segment, backslash,
+    // climb-out, absolute). `dotted`, `dot segments` and `backslashed` above
+    // are three of them; these are the two the set was missing.
+    'climb-out': `../${KB}/.git/${name}`,
+    // Production's own spelling, kept verbatim: it names a directory that
+    // exists on no test machine, so it is the LEXICAL half this covers.
+    absolute: `/app/apps/server/workspaces/main/${KB}/.git/${name}`,
+    // The same family pointed at this run's workspace, so the resolved half
+    // is exercised too — the folder it names is really there.
+    'absolute, in workspace': `{{WORKSPACE_DIR}}/${KB}/.git/${name}`,
     encoded: `${KB}/%2egit/${name}`,
     'double-encoded': `${KB}/%252Egit/${name}`,
     'upper-case': `${KB}/.GIT/${name}`,
     'mixed-case': `${KB}/.Git/${name}`,
     backslashed: `${KB}\\.git\\${name}`,
     symlinked: `${KB}/gitlink/${name}`,
+    // A LINK into the folder, reached through each of those same five
+    // spellings. Nothing in these names is `.git`, so only the resolved half
+    // of the rule sees them — and while that half ran after the normaliser,
+    // every one of them was answered by the path rule instead. This is the
+    // shape that has now broken twice; it is spelled out per family so a
+    // failure names the one that regressed.
+    'symlinked, parent-climb': `${KB}/Notes/../gitlink/${name}`,
+    'symlinked, dot segments': `./${KB}/./gitlink/${name}`,
+    'symlinked, backslashed': `${KB}\\gitlink\\${name}`,
+    'symlinked, climb-out': `../${KB}/gitlink/${name}`,
+    'symlinked, absolute': `{{WORKSPACE_DIR}}/${KB}/gitlink/${name}`,
+    'symlinked, chained link': `${KB}/Notes/../chained/${name}`,
+    // A link named `..link` sitting in the WORKSPACE root: relative to the
+    // root this rule judges against, the spelling begins with `..`, which is
+    // the one shape a `startsWith('..')` climb test swallows. Spelled from
+    // anywhere else (`knowledge-base/..link/…`) it never begins with `..` and
+    // pins nothing.
+    'symlinked, dotted name at the root': `..link/${name}`,
   };
 }
 
+/**
+ * The absolute forms name the workspace on disk, which only exists once the
+ * temp root does — so they carry a placeholder until the test runs.
+ */
+const resolved = (form: string): string => form.replace('{{WORKSPACE_DIR}}', workspaceDir);
+
 /** Every spelling of the git folder ITSELF, for the operations that take a directory. */
 const DIR_FORMS: Record<string, string> = {
   plain: `${KB}/.git`,
@@ -77,6 +112,20 @@ const DIR_FORMS: Record<string, string> = {
   'upper-case': `${KB}/.GIT`,
   symlinked: `${KB}/gitlink`,
   'symlinked, chained': `${KB}/chained`,
+  'symlinked, parent-climb': `${KB}/Notes/../gitlink`,
+  'symlinked, dot segments': `./${KB}/./gitlink`,
+  'symlinked, backslashed': `${KB}\\gitlink`,
+  'symlinked, climb-out': `../${KB}/gitlink`,
+  'symlinked, absolute': `{{WORKSPACE_DIR}}/${KB}/gitlink`,
+  'symlinked, dotted name at the root': `..link`,
+  // The folder ITSELF in the same five families the file forms carry, so every
+  // directory-taking operation — list, mkdir, delete, folder download, unzip
+  // destination — has a regression case for each of them too.
+  'parent-climb': `${KB}/Notes/../.git`,
+  'dot segments': `./${KB}/./.git`,
+  backslashed: `${KB}\\.git`,
+  'climb-out': `../${KB}/.git`,
+  absolute: `{{WORKSPACE_DIR}}/${KB}/.git`,
 };
 
 const FILE_FORMS = { ...fileForms('config'), 'symlinked file': `${KB}/cfglink` };
@@ -107,6 +156,9 @@ beforeEach(async () => {
   await symlink('.git', join(kb, 'gitlink'));
   await symlink('.git/config', join(kb, 'cfglink'));
   await symlink('gitlink', join(kb, 'chained'));
+  // An ordinary name that merely BEGINS with dots — not a climb, and a link by
+  // that name reaches the folder like any other.
+  await symlink(join(KB, '.git'), join(workspaceDir, '..link'));
   const zip = new AdmZip();
   zip.addFile('extracted.md', Buffer.from('# extracted\n'));
   zip.writeZip(join(kb, 'archive.zip'));
@@ -153,28 +205,27 @@ async function listen(app: express.Express): Promise<{ server: Server; baseUrl:
 }
 
 /**
- * The spellings the PATH rule refuses before the git rule is ever consulted:
- * a `..` segment, a `.` segment below a leading `./`, a backslash. One
- * normaliser reads every accepted workspace path now, and it refuses these as
- * paths rather than as git paths — earlier, and with the 400 that says the path
- * could not be placed inside the repository. The git folder is unreachable
- * either way, which is what this file is about; only the sentence differs.
- */
-const UNSPELLABLE = new Set(['dotted', 'dot segments', 'backslashed']);
-
-/**
- * The refusal, whichever rule got there first. Pass the form's name and a
- * spelling the normaliser refuses is checked against ITS answer; leave it out
- * and only the git refusal will do.
+ * The ONE refusal, for every spelling.
+ *
+ * This used to make an exception: the path normaliser refuses a `..` segment,
+ * a `.` segment, a backslash and an absolute path as PATHS, and for a while
+ * that answer — a 400 quoting the spelling back — reached those spellings of a
+ * git path first. Production measured it on all thirteen file tools. The git
+ * rule now reads the caller's raw spelling before anything may rewrite or
+ * refuse it, so no form is answered by anything but the sanitized 403; the
+ * `form` argument is kept so a failure names the spelling that broke.
  */
 async function expectRefused(res: Response, form?: string): Promise<unknown> {
   const body = (await res.json()) as Record<string, unknown>;
-  if (form !== undefined && UNSPELLABLE.has(form)) {
-    expect({ status: res.status, outside: /is outside the knowledge base repository/.test(String(body.error)) }, form)
-      .toEqual({ status: 400, outside: true });
-    return body;
-  }
-  expect({ status: res.status, error: body.error }).toEqual({ status: 403, error: GIT_INTERNALS_MESSAGE });
+  expect(res.status, form).toBe(403);
+  // The WHOLE body, not a search through it: the sanitized message stands
+  // alone, and no field beside it can carry a spelling of the caller's path or
+  // a "use this instead" correction. Two shapes exist — the tool surface
+  // answers `{ error }`, the routes add the error's `kind` — so the one the
+  // answer claims is the one it is held to, exactly.
+  expect(body, form).toEqual(
+    'kind' in body ? { kind: 'git-internals', error: GIT_INTERNALS_MESSAGE } : { error: GIT_INTERNALS_MESSAGE },
+  );
   return body;
 }
 
@@ -276,14 +327,15 @@ describe('workspace tools refuse the git folder', () => {
   for (const [op, args] of fileOps) {
     const tool = op.split(' ')[0];
     describe(op, () => {
-      it.each(Object.entries(FILE_FORMS))('%s form', async (form, p) => {
+      it.each(Object.entries(FILE_FORMS))('%s form', async (form, raw) => {
+        const p = resolved(raw);
         await expectRefused(await call(tool, args(p)), form);
       });
 
       it('answers a missing path exactly as an existing one', async () => {
         for (const form of Object.keys(MISSING_FORMS)) {
-          const existing = await call(tool, args(fileForms('config')[form]));
-          const missing = await call(tool, args(MISSING_FORMS[form]));
+          const existing = await call(tool, args(resolved(fileForms('config')[form])));
+          const missing = await call(tool, args(resolved(MISSING_FORMS[form])));
           expect(missing.status, form).toBe(existing.status);
           // Compared with the file name put back. A spelling the PATH rule
           // refuses is answered on the spelling alone, and that answer QUOTES
@@ -301,7 +353,8 @@ describe('workspace tools refuse the git folder', () => {
 
   for (const [op, args] of dirOps) {
     const tool = op.split(' ')[0];
-    it.each(Object.entries(DIR_FORMS))(`${op} — %s form`, async (form, p) => {
+    it.each(Object.entries(DIR_FORMS))(`${op} — %s form`, async (form, raw) => {
+      const p = resolved(raw);
       await expectRefused(await call(tool, args(p)), form);
     });
   }
@@ -444,14 +497,15 @@ describe('workspace routes refuse the git folder', () => {
       // No form passed: on this surface the git guard is mounted ahead of every
       // handler on the `/workspace/:id` prefix, so it answers before the
       // normaliser is ever asked — the one 403, in every spelling, as before.
-      it.each(Object.entries(FILE_FORMS))('%s form', async (_form, p) => {
+      it.each(Object.entries(FILE_FORMS))('%s form', async (_form, raw) => {
+        const p = resolved(raw);
         await expectRefused(await send(p));
       });
 
       it('answers a missing path exactly as an existing one', async () => {
         for (const form of Object.keys(MISSING_FORMS)) {
-          const existing = await send(fileForms('config')[form]);
-          const missing = await send(MISSING_FORMS[form]);
+          const existing = await send(resolved(fileForms('config')[form]));
+          const missing = await send(resolved(MISSING_FORMS[form]));
           expect(missing.status).toBe(existing.status);
           expect(await missing.json()).toEqual(await existing.json());
         }
@@ -460,7 +514,8 @@ describe('workspace routes refuse the git folder', () => {
   }
 
   for (const [name, send] of dirRoutes) {
-    it.each(Object.entries(DIR_FORMS))(`${name} — %s form`, async (_form, p) => {
+    it.each(Object.entries(DIR_FORMS))(`${name} — %s form`, async (_form, raw) => {
+      const p = resolved(raw);
       await expectRefused(await send(p));
     });
   }
@@ -533,23 +588,58 @@ describe('WorkspaceService refuses the git folder on its own', () => {
   ];
 
   for (const [name, run] of ops) {
-    it.each(Object.entries(fileForms('config')).filter(([form]) => !(name === 'readFileAtRef' && form === 'symlinked')))(
+    // `readFileAtRef` reads a path out of a git REF, never off the working
+    // tree, so no link on disk is followed and the link spellings do not
+    // apply to it — a ref read of a link's path yields the link's own blob
+    // (the target's NAME), never anything from inside the folder.
+    it.each(
+      Object.entries(fileForms('config')).filter(
+        ([form]) => !(name === 'readFileAtRef' && form.startsWith('symlinked')),
+      ),
+    )(
       `${name} — %s form`,
-      async (form, p) => {
-        const err = await run(p).catch((e: unknown) => e);
-        // `readFileAtRef` takes a REPO-relative path (it strips the prefix
-        // above), so it is not a workspace path and does not meet the
-        // normaliser; every other op does, and for the spellings the path rule
-        // refuses that refusal is the one that answers.
-        if (UNSPELLABLE.has(form) && name !== 'readFileAtRef') {
-          expect((err as Error).message, form).toMatch(/is outside the knowledge base repository/);
-          return;
-        }
-        expect(err).toBeInstanceOf(GitInternalsError);
+      async (form, raw) => {
+        const err = await run(resolved(raw)).catch((e: unknown) => e);
+        expect(err, form).toBeInstanceOf(GitInternalsError);
       },
     );
   }
 
+  it('a ref read of a link path reads the REF, not the folder the link points into', async () => {
+    // The exception the matrix above excludes, asserted rather than assumed:
+    // `readFileAtRef` runs `git show <ref>:<path>`, which reads out of the
+    // object database and never follows a link on disk. A ref read of a link's
+    // path yields the link's own blob — the target's NAME — so there is
+    // nothing from inside the folder to refuse, and refusing it would take a
+    // legitimate read away. The git rule still refuses every LITERAL spelling.
+    const gitRunner = {
+      defaultTimeoutMs: 1000,
+      run: vi.fn(async (_cwd: string, args: string[]) => {
+        // What `git show` really answers for a link's path: its target name.
+        expect(args[0]).toBe('show');
+        return { stdout: '.git\n', stderr: '', code: 0 };
+      }),
+    };
+    const refService = new WorkspaceService(root, 'https://example.invalid/kb.git', KB, new NodeFs(), 'x-access-token', gitRunner as never);
+
+    for (const [form, raw] of Object.entries(fileForms('config'))) {
+      if (!form.startsWith('symlinked')) continue;
+      // The service takes a repo-relative path here, as its callers pass it.
+      const repoPath = resolved(raw).replace(`${KB}/`, '');
+      const result = await refService.readFileAtRef(WS, 'main', repoPath).catch((e: unknown) => e);
+      expect(result, form).not.toBeInstanceOf(GitInternalsError);
+    }
+    expect(gitRunner.run).toHaveBeenCalled();
+
+    // …while a literal git path at a ref is still refused, whatever its form.
+    for (const [form, raw] of Object.entries(fileForms('config'))) {
+      if (form.startsWith('symlinked')) continue;
+      const repoPath = resolved(raw).replace(`${KB}/`, '');
+      const err = await refService.readFileAtRef(WS, 'main', repoPath).catch((e: unknown) => e);
+      expect(err, form).toBeInstanceOf(Error);
+    }
+  });
+
   it('a folder download leaves out a git folder spelled in another case', async () => {
     const upper = join(workspaceDir, KB, 'Notes', '.GIT');
     await mkdir(upper, { recursive: true });
@@ -641,7 +731,7 @@ describe('the route guard on its own', () => {
 
   it('refuses every spelling before the route runs, even unauthenticated', async () => {
     userId = undefined;
-    const spellings = Object.values(FILE_FORMS);
+    const spellings = Object.values(FILE_FORMS).map(resolved);
     for (const p of spellings) {
       const res = await fetch(`${baseUrl}/api/workspace/${WS}/anything?path=${encodeURIComponent(p)}`);
       // Every spelling that NAMES the folder is refused with no disk touched.
@@ -702,7 +792,8 @@ describe('DiffService refuses the git folder on its own', () => {
   ];
 
   for (const [name, run] of ops) {
-    it.each(Object.entries(FILE_FORMS))(`${name} — %s form`, async (_form, p) => {
+    it.each(Object.entries(FILE_FORMS))(`${name} — %s form`, async (_form, raw) => {
+      const p = resolved(raw);
       await expect(run(p)).rejects.toBeInstanceOf(GitInternalsError);
     });
   }
@@ -740,7 +831,7 @@ describe('agent filesystems refuse the git folder on their own', () => {
       { basePath: workspaceDir, contained: true },
       { workflow: workflow as unknown as IWorkflowService, workspaceId: WS, branch: BRANCH, user: USER, kbDirName: KB },
     );
-    for (const p of Object.values(FILE_FORMS)) {
+    for (const p of Object.values(FILE_FORMS).map(resolved)) {
       await expect(lockingFs.readFile(p)).rejects.toBeInstanceOf(GitInternalsError);
       await expect(lockingFs.stat(p)).rejects.toBeInstanceOf(GitInternalsError);
       await expect(lockingFs.writeFile(p, 'x')).rejects.toBeInstanceOf(GitInternalsError);
@@ -750,7 +841,7 @@ describe('agent filesystems refuse the git folder on their own', () => {
       await expect(lockingFs.moveFile(p, `${KB}/Notes/b.md`)).rejects.toBeInstanceOf(GitInternalsError);
       await expect(lockingFs.writeFiles([{ path: p, content: 'x' }], 'batch')).rejects.toBeInstanceOf(GitInternalsError);
     }
-    for (const p of Object.values(DIR_FORMS)) {
+    for (const p of Object.values(DIR_FORMS).map(resolved)) {
       await expect(lockingFs.readdir(p)).rejects.toBeInstanceOf(GitInternalsError);
       await expect(lockingFs.mkdir(`${p}/new`)).rejects.toBeInstanceOf(GitInternalsError);
     }
@@ -760,7 +851,7 @@ describe('agent filesystems refuse the git folder on their own', () => {
 
   it('ReadOnlyFilesystem answers a git path with the git refusal, not the read-only one', async () => {
     const readOnly = new ReadOnlyFilesystem({ basePath: workspaceDir, contained: true });
-    for (const p of Object.values(FILE_FORMS)) {
+    for (const p of Object.values(FILE_FORMS).map(resolved)) {
       await expect(readOnly.readFile(p)).rejects.toBeInstanceOf(GitInternalsError);
       await expect(readOnly.exists(p)).rejects.toBeInstanceOf(GitInternalsError);
       await expect(readOnly.writeFile(p, 'x')).rejects.toBeInstanceOf(GitInternalsError);

package/src/modules/workspace/workspace.service.ts

@@ -995,6 +995,14 @@ export class WorkspaceService implements IWorkspaceService {
    * is the path the operation will use, and a spelling that normalises inside
    * and resolves outside is exactly the miss this check exists to catch.
    *
+   * The git rule reads the caller's RAW spelling before either step — the
+   * whole rule, links resolved, not just the spelling. Those two refuse
+   * `.`/`..`, backslashes and absolute paths with a message that quotes the
+   * path back and names a corrected one, and a git path spelled any of those
+   * ways was answered by THAT rather than by the one sanitized refusal
+   * (measured in production), as was a LINK into the folder spelled the same
+   * ways. Which rule speaks is not the caller's to choose.
+   *
    * Callers use the returned `relativePath` for everything downstream — the
    * git-internals check, the diff baseline, the lock-free path turns, their own
    * error messages — so what is checked is what is written. Nine inline
@@ -1006,6 +1014,7 @@ export class WorkspaceService implements IWorkspaceService {
     wsPath: string,
   ): Promise<{ workspaceDir: string; relativePath: string; absolutePath: string }> {
     const workspaceDir = await this.resolveWorkspaceDir(workspaceId);
+    await assertNotGitInternals(workspaceDir, wsPath); // The RAW spelling, first — see above.
     const relativePath = normalizeWorkspacePath(wsPath, this.kbDirName);
     const absolutePath = path.resolve(workspaceDir, relativePath);
     assertWithinDirectory(absolutePath, this.repoRoot(workspaceDir));

package/src/modules/workspace/workspace.tools.ts

@@ -23,7 +23,7 @@ import { workspaceIdForBranch } from '../../shared/workspace-id.js';
 import { assertValidBranchName } from '../kb-fs/branch-name.js';
 import { assertInsideRepo, assertRepoRootNameFreeArgs, normalizePathArgs } from '../kb-fs/repo-path.js';
 import { GitGuardedFilesystem } from '../kb-fs/git-guarded-filesystem.js';
-import { assertNoGitInternalsSegment, hasGitInternalsSegment } from '../../shared/git-internals.js';
+import { assertNoGitInternalsSegment, assertNotGitInternals, hasGitInternalsSegment } from '../../shared/git-internals.js';
 import { isRolesYamlPath } from '../access-model/roles-yaml-guard.js';
 import type { ISessionSink } from './session-sink.js';
 import { isAbsence } from '../../shared/fs.contract.js';
@@ -782,7 +782,7 @@ export function registerWorkspaceTools(
    * not cloned yet (or that does not resolve) is left to the handler; the
    * filesystem refuses again underneath regardless.
    */
-  const assertToolPathsNotGitInternals = async (args: Record<string, unknown>, ctx: ToolContext): Promise<void> => {
+  const toolPathArgs = (args: Record<string, unknown>): string[] => {
     const paths: string[] = [];
     for (const key of ['path', 'src', 'dest', 'destination'] as const) {
       if (typeof args[key] === 'string') paths.push(args[key]);
@@ -793,18 +793,52 @@ export function registerWorkspaceTools(
         if (typeof fp === 'string') paths.push(fp);
       }
     }
-    for (const p of paths) assertNoGitInternalsSegment(p);
-    const onDisk = paths.filter((p) => !spillStore.isSpillRef(p));
-    if (onDisk.length === 0 || typeof args.branch !== 'string' || args.branch === '') return;
-    let fs: LocalFilesystem;
+    return paths;
+  };
+
+  /**
+   * The branch's workspace root, to judge a spelling against what is on disk
+   * — or null when there is nothing to judge it against yet. Only a branch
+   * ALREADY cloned is used: bootstrapping one here would clone before the
+   * handler's access and ontology gates have had their say.
+   */
+  const gitCheckRootFor = async (args: Record<string, unknown>, ctx: ToolContext): Promise<string | null> => {
+    if (typeof args.branch !== 'string' || args.branch === '') return null;
     try {
-      if (!(await ctx.workspaceService.hasBootstrappedWorkspace(workspaceIdForBranch(args.branch)))) return;
-      fs = await ctx.getFilesystem(args.branch);
+      if (!(await ctx.workspaceService.hasBootstrappedWorkspace(workspaceIdForBranch(args.branch)))) return null;
+      const fs = await ctx.getFilesystem(args.branch);
+      return fs instanceof GitGuardedFilesystem ? fs.basePath : null;
     } catch {
-      return;
+      return null;
     }
-    if (!(fs instanceof GitGuardedFilesystem)) return;
-    for (const p of onDisk) await fs.assertNotGitInternals(p);
+  };
+
+  /**
+   * The WHOLE rule — the spelling and where it lands, links resolved — over
+   * the caller's own arguments, before any gate, lock or read.
+   *
+   * Run before `normalizePathArgs`, which refuses a `..` segment, a `.`
+   * segment, a backslash and an absolute path as PATHS: a 400 that quotes the
+   * spelling back and names a corrected one. That answer used to arrive first
+   * for five families of spelling, so `knowledge-base/Notes/../.git/config`
+   * was told which path it meant instead of being refused. Running only the
+   * LEXICAL half here fixed those and left the same hole one step along: a
+   * link into the folder (`Notes/../gitlink/config`) has no `.git` to read in
+   * its spelling, so it took the path rule's answer too. Both halves therefore
+   * read the caller's spelling before anything may rewrite or refuse it.
+   *
+   * Nothing under the folder was reachable through any of it — the filesystem
+   * refuses again underneath — but which rule answers is not the caller's to
+   * choose by how they spell the path.
+   */
+  const assertToolPathsNotGitInternals = async (args: Record<string, unknown>, ctx: ToolContext): Promise<void> => {
+    const paths = toolPathArgs(args);
+    for (const p of paths) assertNoGitInternalsSegment(p);
+    const onDisk = paths.filter((p) => !spillStore.isSpillRef(p));
+    if (onDisk.length === 0) return;
+    const root = await gitCheckRootFor(args, ctx);
+    if (root === null) return;
+    for (const p of onDisk) await assertNotGitInternals(root, p);
   };
 
   // ── preflight for moves and deletes ─────────────────────────────────────
@@ -1188,6 +1222,8 @@ export function registerWorkspaceTools(
       // never reached the repository — the whole bug, spelled with a prefix.
       toolHandler(
         async (args, ctx) => {
+          // BEFORE the normaliser: see `assertToolPathsNotGitInternals`.
+          if (spec.fileTool !== false) await assertToolPathsNotGitInternals(args, ctx);
           const normalized = normalizePathArgs(
             args,
             kbDirName,

package/src/shared/__tests__/git-internals.test.ts

@@ -98,6 +98,47 @@ describe('assertNotGitInternals — the resolved form', () => {
     await expect(assertNotGitInternals(root, 'knowledge-base/dangling')).rejects.toMatchObject({ code: 'EACCES' });
   });
 
+  it.each(['/etc/shadow', '../../../../etc/shadow', '/proc/1/root/secret'])(
+    'never probes a spelling that lands outside the workspace on disk: %s',
+    async (outside) => {
+      // A raw spelling fans out into candidates, and one can name somewhere
+      // the server may not read. Probing it would answer with that place's own
+      // EACCES instead of the path rule's typed refusal for a spelling that
+      // was never a workspace path — so the disk is only asked about
+      // candidates that land under the root. The lexical reading still judges
+      // the rest, which is what catches a climb into another checkout's .git.
+      const realpath = fs.realpath.bind(fs);
+      const asked: string[] = [];
+      vi.spyOn(fs, 'realpath').mockImplementation((async (p: string) => {
+        asked.push(p);
+        if (!p.startsWith(root)) throw Object.assign(new Error('EACCES: permission denied'), { code: 'EACCES' });
+        return realpath(p);
+      }) as typeof fs.realpath);
+
+      await expect(assertNotGitInternals(root, outside)).resolves.toBeUndefined();
+      expect(asked.filter((p) => !p.startsWith(root))).toEqual([]);
+    },
+  );
+
+  it.each(['..link', '..link/config', './..link/config', '..dir/deeper'])(
+    'probes a name that merely BEGINS with dots, and refuses it when it lands in the folder: %s',
+    async (p) => {
+      // Judged from the folder these sit DIRECTLY in, which is where the
+      // outside-the-root test can mistake them: relative to that root, the
+      // whole path is `..link/…`. `..link` is not a climb — it is a file name
+      // — so it is probed like any other entry, or a link by that name reaches
+      // the folder unchecked.
+      const kb = path.join(root, 'knowledge-base');
+      await fs.symlink('.git', path.join(kb, '..link'));
+      await fs.symlink('.git', path.join(kb, '..dir'));
+      await expect(assertNotGitInternals(kb, p)).rejects.toBeInstanceOf(GitInternalsError);
+    },
+  );
+
+  it('still refuses a climb into another checkout’s git folder, which is judged without the disk', async () => {
+    await expect(assertNotGitInternals(root, '../other-checkout/.git/config')).rejects.toBeInstanceOf(GitInternalsError);
+  });
+
   it('a link loop is no refusal of its own, and does not hang', async () => {
     await expect(assertNotGitInternals(root, 'knowledge-base/loop-a')).resolves.toBeUndefined();
   });