clay-server 4.3.0 → 4.3.1-beta.1

package/lib/project-file-http.js

@@ -0,0 +1,56 @@
+var fs = require("fs");
+var path = require("path");
+var attachRequestAccess = require("./project-request-access").attachRequestAccess;
+var resolveFilePath = require("./project-file-path").resolveFilePath;
+var fileError = require("./project-file-path").fileError;
+
+var MIME_TYPES = {
+  ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg",
+  ".gif": "image/gif", ".webp": "image/webp", ".svg": "image/svg+xml",
+  ".bmp": "image/bmp", ".ico": "image/x-icon",
+};
+
+function attachFileHTTP(ctx) {
+  var access = ctx.requestAccess || attachRequestAccess(Object.assign({}, ctx, {
+    getOsUserInfoForWs: ctx.getOsUserInfoForReq,
+  }));
+
+  function handleHTTP(req, res, urlPath) {
+    var download = urlPath.startsWith("/api/file/download?");
+    if (req.method !== "GET" || (!download && !urlPath.startsWith("/api/file?"))) return false;
+    try {
+      var scope = access.fileScope(req);
+      var requested = new URLSearchParams(urlPath.substring(urlPath.indexOf("?"))).get("path");
+      var file = resolveFilePath(ctx.cwd, requested, scope);
+      var mime = MIME_TYPES[path.extname(file).toLowerCase()];
+      if (!download && !mime) {
+        res.writeHead(403); res.end("Only image files"); return true;
+      }
+      var content = scope.identity ? ctx.fsAsUser("read_binary", { file: file }, scope.identity).buffer : fs.readFileSync(file);
+      var headers = {
+        "Content-Type": download ? "application/octet-stream" : mime,
+        "Content-Length": content.length,
+        "Cache-Control": "no-store",
+        "X-Content-Type-Options": "nosniff",
+      };
+      if (download) {
+        var name = path.basename(requested).replace(/[\x00-\x1f\x7f"\\]/g, "_") || "download";
+        var ascii = name.replace(/[^\x20-\x7e]/g, "_");
+        var encoded = encodeURIComponent(name).replace(/[!'()*]/g, function (character) {
+          return "%" + character.charCodeAt(0).toString(16).toUpperCase();
+        });
+        headers["Content-Disposition"] = "attachment; filename=\"" + ascii + "\"; filename*=UTF-8''" + encoded;
+      }
+      res.writeHead(200, headers);
+      res.end(content);
+    } catch (error) {
+      var result = fileError(error);
+      res.writeHead(result.status, { "Content-Type": "text/plain; charset=utf-8", "Cache-Control": "no-store" });
+      res.end(result.message);
+    }
+    return true;
+  }
+  return { handleHTTP: handleHTTP };
+}
+
+module.exports = { attachFileHTTP: attachFileHTTP };

package/lib/project-file-path.js

@@ -1,13 +1,49 @@
 var path = require("path");
+var fs = require("fs");
 
-// Resolve a file-browser target in the caller's project namespace. Ordinary
-// mode delegates to safePath, which enforces the realpath/symlink boundary.
-// OS-user mode deliberately returns the project-relative absolute target and
-// leaves access enforcement to the mapped user's filesystem operation.
-function resolveFilePath(cwd, requested, safePath, osUserInfo) {
-  if (typeof requested !== "string" || !requested) return null;
-  if (osUserInfo) return path.resolve(cwd, requested);
-  return typeof safePath === "function" ? safePath(cwd, requested) : null;
+function failure(code, message) {
+  var error = new Error(message);
+  error.code = code;
+  return error;
 }
 
-module.exports = { resolveFilePath: resolveFilePath };
+function inside(base, target) {
+  var relative = path.relative(base, target);
+  return relative !== ".." && !relative.startsWith(".." + path.sep) && !path.isAbsolute(relative);
+}
+
+// Scope is server-derived for each request. In personal and mapped OS-user
+// modes, the actual filesystem operation enforces read/write permissions.
+// Unmapped multi-user deployments retain the project and symlink boundary.
+function resolveFilePath(cwd, requested, scope) {
+  if (typeof requested !== "string" || !requested || requested.indexOf("\0") !== -1) {
+    throw failure("INVALID_PATH", "Invalid file path");
+  }
+  var resolved = path.resolve(cwd, requested);
+  if (scope && scope.projectBound === false) return resolved;
+  if (!inside(path.resolve(cwd), resolved)) {
+    throw failure("FILE_SCOPE", "This file is outside your project's allowed file scope");
+  }
+  var base = fs.realpathSync(cwd);
+  var real = fs.realpathSync(resolved);
+  if (!inside(base, real)) {
+    throw failure("FILE_SCOPE", "This file links outside your project's allowed file scope");
+  }
+  return real;
+}
+
+function fileError(error) {
+  var code = error.code;
+  // OS-user helpers report child-process failures through stderr.
+  if (error.stderr) {
+    var match = String(error.stderr).match(/code: ['"](EACCES|EPERM|ENOENT|ENOTDIR)['"]/);
+    if (match) code = match[1];
+  }
+  if (code === "ENOENT" || code === "ENOTDIR") return { code: code, status: 404, message: "File or folder not found" };
+  if (code === "EACCES" || code === "EPERM") return { code: code, status: 403, message: "The operating system denied access for your account" };
+  if (code === "INVALID_PATH") return { code: code, status: 400, message: error.message };
+  if (code === "FILE_SCOPE" || code === "FILE_FORBIDDEN" || code === "OS_IDENTITY") return { code: code, status: 403, message: error.message };
+  return { code: code || "FILE_ERROR", status: 500, message: error.message || "File operation failed" };
+}
+
+module.exports = { resolveFilePath: resolveFilePath, fileError: fileError, failure: failure };

package/lib/project-file-watch.js

@@ -6,34 +6,28 @@ var resolveFilePath = require("./project-file-path").resolveFilePath;
  * Attach file/directory watcher engine to a project context.
  *
  * ctx fields:
- *   cwd, send, sendTo, safePath, BINARY_EXTS, FS_MAX_SIZE, IGNORED_DIRS, requestAccess, fsAsUser
+ *   cwd, send, sendTo, BINARY_EXTS, FS_MAX_SIZE, IGNORED_DIRS, requestAccess, fsAsUser
  */
 function attachFileWatch(ctx) {
   var cwd = ctx.cwd;
   var send = ctx.send;
   var sendTo = ctx.sendTo;
-  var safePath = ctx.safePath;
   var BINARY_EXTS = ctx.BINARY_EXTS;
   var FS_MAX_SIZE = ctx.FS_MAX_SIZE;
   var IGNORED_DIRS = ctx.IGNORED_DIRS;
   var access = ctx.requestAccess;
   var osUsers = !!ctx.osUsers;
 
-  function identityFor(client) {
+  function scopeFor(client) {
     if (!access) {
       if (osUsers) throw new Error("OS user identity is unavailable");
-      return null;
+      return { identity: null, projectBound: true };
     }
-    if (!access.canUseFiles(client)) throw new Error("File browser access is not permitted");
-    var identity = access.osIdentity(client);
-    if (osUsers && !identity) throw new Error("OS user identity is unavailable");
-    return identity;
+    return access.fileScope(client);
   }
 
-  function checkedPath(relPath, identity) {
-    var resolved = resolveFilePath(cwd, relPath, safePath, osUsers ? identity : null);
-    if (!resolved) throw new Error("Access denied");
-    return resolved;
+  function checkedPath(relPath, scope) {
+    return resolveFilePath(cwd, relPath, scope);
   }
 
   // --- File watcher ---
@@ -68,8 +62,9 @@ function attachFileWatch(ctx) {
   }
 
   function readFileSnapshot(client, relPath) {
-    var identity = identityFor(client);
-    var absPath = checkedPath(relPath, identity);
+    var scope = scopeFor(client);
+    var identity = scope.identity;
+    var absPath = checkedPath(relPath, scope);
     var stat = identity ? ctx.fsAsUser("stat", { file: absPath }, identity) : fs.statSync(absPath);
     var ext = path.extname(absPath).toLowerCase();
     if (stat.size > FS_MAX_SIZE || BINARY_EXTS.has(ext)) return null;
@@ -107,10 +102,8 @@ function attachFileWatch(ctx) {
       relPath = client;
       client = null;
     }
-    var identity;
-    try { identity = identityFor(client); } catch (error) { return Promise.resolve(false); }
-    var absPath = resolveFilePath(cwd, relPath, safePath, osUsers ? identity : null);
-    if (!absPath) return Promise.resolve(false);
+    var absPath;
+    try { absPath = checkedPath(relPath, scopeFor(client)); } catch (error) { return Promise.resolve(false); }
     var key = client || "_legacy";
     var existing = fileWatchers.get(key);
     if (existing && existing.relPath === relPath) return existing.ready;
@@ -186,8 +179,9 @@ function attachFileWatch(ctx) {
   var dirWatchers = new Map();
 
   function readDirectory(client, relPath) {
-    var identity = identityFor(client);
-    var absPath = checkedPath(relPath, identity);
+    var scope = scopeFor(client);
+    var identity = scope.identity;
+    var absPath = checkedPath(relPath, scope);
     var items = identity ? ctx.fsAsUser("list", { dir: absPath }, identity) :
       fs.readdirSync(absPath, { withFileTypes: true }).map(function (item) {
         return { name: item.name, isDir: item.isDirectory() };
@@ -204,12 +198,12 @@ function attachFileWatch(ctx) {
     var subscriptions = dirWatchers.get(client);
     if (!subscriptions) { subscriptions = new Map(); dirWatchers.set(client, subscriptions); }
     if (subscriptions.has(relPath)) return;
-    var identity;
+    var scope;
     try {
-      identity = identityFor(client);
+      scope = scopeFor(client);
       readDirectory(client, relPath);
       var entry = { watcher: null, debounce: null };
-      entry.watcher = fs.watch(checkedPath(relPath, identity), function () {
+      entry.watcher = fs.watch(checkedPath(relPath, scope), function () {
         clearTimeout(entry.debounce);
         entry.debounce = setTimeout(function () {
           try {

package/lib/project-filesystem.js

@@ -3,6 +3,7 @@ var path = require("path");
 var attachRequestAccess = require("./project-request-access").attachRequestAccess;
 var attachFileHistory = require("./project-file-history").attachFileHistory;
 var resolveFilePath = require("./project-file-path").resolveFilePath;
+var fileError = require("./project-file-path").fileError;
 
 /**
  * Attach filesystem-related message handlers to a project context.
@@ -11,7 +12,6 @@ var resolveFilePath = require("./project-file-path").resolveFilePath;
  *   cwd, slug, osUsers
  *   sm (session manager)
  *   send, sendTo
- *   safePath, safeAbsPath (functions)
  *   getOsUserInfoForWs (function)
  *   startFileWatch, stopFileWatch, startDirWatch (from _fileWatch)
  *   usersModule, fsAsUser
@@ -23,8 +23,6 @@ function attachFilesystem(ctx) {
   var cwd = ctx.cwd;
   var slug = ctx.slug;
   var sendTo = ctx.sendTo;
-  var safePath = ctx.safePath;
-  var safeAbsPath = ctx.safeAbsPath;
   var startFileWatch = ctx.startFileWatch;
   var stopFileWatch = ctx.stopFileWatch;
   var startDirWatch = ctx.startDirWatch;
@@ -41,26 +39,26 @@ function attachFilesystem(ctx) {
   var fileHistory = attachFileHistory(ctx, access);
 
   function handleFilesystemMessage(ws, msg) {
-    // Unsubscription must remain available after permission revocation.
+    var fileScope;
+    var fileTarget;
+    // Resolve live authority before every operation; never trust message roles.
     if (/^fs_/.test(msg.type) && msg.type !== "fs_unwatch") {
-      if (!access.canUseFiles(ws)) {
-        sendTo(ws, { type: msg.type + "_result", path: msg.path, requestId: msg.requestId, projectSlug: msg.projectSlug, sessionId: msg.sessionId, accountId: msg.accountId, error: "File browser access is not permitted" });
-        return true;
-      }
-      try { access.osIdentity(ws); } catch (e) {
-        sendTo(ws, { type: msg.type + "_result", path: msg.path, requestId: msg.requestId, projectSlug: msg.projectSlug, sessionId: msg.sessionId, accountId: msg.accountId, error: e.message });
+      try {
+        fileScope = access.fileScope(ws);
+        if (/^fs_(list|read|write|watch)$/.test(msg.type)) {
+          fileTarget = resolveFilePath(cwd, msg.type === "fs_list" ? msg.path || "." : msg.path, fileScope);
+        }
+      } catch (e) {
+        var denied = fileError(e);
+        sendTo(ws, { type: msg.type + "_result", path: msg.path, requestId: msg.requestId, projectSlug: msg.projectSlug, sessionId: msg.sessionId, accountId: msg.accountId, ok: false, error: denied.message, errorCode: denied.code });
         return true;
       }
     }
 
     // --- fs_list ---
     if (msg.type === "fs_list") {
-      var fsListIdentity = access.osIdentity(ws);
-      var fsDir = resolveFilePath(cwd, msg.path || ".", safePath, fsListIdentity);
-      if (!fsDir) {
-        sendTo(ws, { type: "fs_list_result", path: msg.path, entries: [], error: "Access denied" });
-        return true;
-      }
+      var fsListIdentity = fileScope.identity;
+      var fsDir = fileTarget;
       try {
         var fsListUserInfo = fsListIdentity;
         var entries = [];
@@ -92,7 +90,7 @@ function attachFilesystem(ctx) {
         // Auto-watch the directory for changes
         startDirWatch(ws, msg.path || ".");
       } catch (e) {
-        sendTo(ws, { type: "fs_list_result", path: msg.path, entries: [], error: e.message });
+        sendTo(ws, { type: "fs_list_result", path: msg.path, entries: [], error: fileError(e).message, errorCode: fileError(e).code });
       }
       return true;
     }
@@ -138,19 +136,15 @@ function attachFilesystem(ctx) {
         walkDir(cwd, "");
         sendTo(ws, { type: "fs_search_result", query: msg.query, entries: searchResults });
       } catch (e) {
-        sendTo(ws, { type: "fs_search_result", query: msg.query, entries: [], error: e.message });
+        sendTo(ws, { type: "fs_search_result", query: msg.query, entries: [], error: fileError(e).message, errorCode: fileError(e).code });
       }
       return true;
     }
 
     // --- fs_read ---
     if (msg.type === "fs_read") {
-      var fsReadIdentity = access.osIdentity(ws);
-      var fsFile = resolveFilePath(cwd, msg.path, safePath, fsReadIdentity);
-      if (!fsFile) {
-        sendTo(ws, { type: "fs_read_result", path: msg.path, requestId: msg.requestId, projectSlug: msg.projectSlug, sessionId: msg.sessionId, accountId: msg.accountId, error: "Access denied" });
-        return true;
-      }
+      var fsReadIdentity = fileScope.identity;
+      var fsFile = fileTarget;
       try {
         var fsReadUserInfo = fsReadIdentity;
         var ext = path.extname(fsFile).toLowerCase();
@@ -185,19 +179,15 @@ function attachFilesystem(ctx) {
           sendTo(ws, { type: "fs_read_result", path: msg.path, requestId: msg.requestId, projectSlug: msg.projectSlug, sessionId: msg.sessionId, accountId: msg.accountId, content: content, size: stat.size });
         }
       } catch (e) {
-        sendTo(ws, { type: "fs_read_result", path: msg.path, requestId: msg.requestId, projectSlug: msg.projectSlug, sessionId: msg.sessionId, accountId: msg.accountId, error: e.message });
+        sendTo(ws, { type: "fs_read_result", path: msg.path, requestId: msg.requestId, projectSlug: msg.projectSlug, sessionId: msg.sessionId, accountId: msg.accountId, error: fileError(e).message, errorCode: fileError(e).code });
       }
       return true;
     }
 
     // --- fs_write ---
     if (msg.type === "fs_write") {
-      var fsWriteIdentity = access.osIdentity(ws);
-      var fsWriteFile = resolveFilePath(cwd, msg.path, safePath, fsWriteIdentity);
-      if (!fsWriteFile) {
-        sendTo(ws, { type: "fs_write_result", path: msg.path, ok: false, error: "Access denied" });
-        return true;
-      }
+      var fsWriteIdentity = fileScope.identity;
+      var fsWriteFile = fileTarget;
       try {
         var fsWriteUserInfo = fsWriteIdentity;
         if (fsWriteUserInfo) {
@@ -207,7 +197,7 @@ function attachFilesystem(ctx) {
         }
         sendTo(ws, { type: "fs_write_result", path: msg.path, ok: true });
       } catch (e) {
-        sendTo(ws, { type: "fs_write_result", path: msg.path, ok: false, error: e.message });
+        sendTo(ws, { type: "fs_write_result", path: msg.path, ok: false, error: fileError(e).message, errorCode: fileError(e).code });
       }
       return true;
     }

package/lib/project-http.js

@@ -6,24 +6,9 @@ var { execFileSync, spawn } = require("child_process");
 var defaultFsAsUser = require("./os-users").fsAsUser;
 var defaultUsersModule = require("./users");
 var gitCli = require("./git-cli");
-var resolveFilePath = require("./project-file-path").resolveFilePath;
+var attachFileHTTP = require("./project-file-http").attachFileHTTP;
 var sharedSkillDiscovery = require("./yoke/skill-discovery");
 
-var IMAGE_EXTS = new Set([".png", ".jpg", ".jpeg", ".gif", ".webp", ".svg", ".bmp", ".ico"]);
-var MIME_TYPES = {
-  ".html": "text/html",
-  ".css": "text/css",
-  ".js": "application/javascript",
-  ".json": "application/json",
-  ".png": "image/png",
-  ".jpg": "image/jpeg",
-  ".jpeg": "image/jpeg",
-  ".gif": "image/gif",
-  ".webp": "image/webp",
-  ".svg": "image/svg+xml",
-  ".bmp": "image/bmp",
-  ".ico": "image/x-icon",
-};
 var MAX_UPLOAD_BYTES = 50 * 1024 * 1024; // 50 MB
 
 function parseJsonBody(req) {
@@ -42,7 +27,7 @@ function parseJsonBody(req) {
  *
  * ctx fields:
  *   cwd, slug, project, sm, send, sendTo, imagesDir, osUsers, pushModule,
- *   safePath, safeAbsPath, getOsUserInfoForReq, sendExtensionCommandAny,
+ *   requestAccess, getOsUserInfoForReq, sendExtensionCommandAny,
  *   saveGeneratedImageToProject, _extToken, _browserTabList
  */
 function attachHTTP(ctx) {
@@ -56,8 +41,6 @@ function attachHTTP(ctx) {
   var saveGeneratedImageToProject = ctx.saveGeneratedImageToProject;
   var osUsers = ctx.osUsers;
   var pushModule = ctx.pushModule;
-  var safePath = ctx.safePath;
-  var safeAbsPath = ctx.safeAbsPath;
   var getOsUserInfoForReq = ctx.getOsUserInfoForReq;
   var fsAsUser = ctx.fsAsUser || defaultFsAsUser;
   var usersModule = ctx.usersModule || defaultUsersModule;
@@ -65,6 +48,10 @@ function attachHTTP(ctx) {
   var _extToken = ctx._extToken;
   var _browserTabList = ctx._browserTabList;
 
+  var fileHTTP = attachFileHTTP(Object.assign({}, ctx, {
+    usersModule: usersModule, fsAsUser: fsAsUser,
+  }));
+
   function handleHTTP(req, res, urlPath) {
     // Browser MCP extension bridge: forward commands to Chrome extension
     if (req.method === "POST" && urlPath === "/ext-command") {
@@ -291,92 +278,7 @@ function attachHTTP(ctx) {
       return true;
     }
 
-    // File browser: download project files
-    if (req.method === "GET" && urlPath.startsWith("/api/file/download?")) {
-      if (usersModule.isMultiUser()) {
-        var downloadUser = req._clayUser;
-        var downloadPermissions = downloadUser ? usersModule.getEffectivePermissions(downloadUser, osUsers) : null;
-        if (!downloadPermissions || !downloadPermissions.fileBrowser) {
-          res.writeHead(403, { "Content-Type": "text/plain; charset=utf-8" });
-          res.end("File browser access is not permitted");
-          return true;
-        }
-      }
-
-      var downloadQueryIndex = urlPath.indexOf("?");
-      var downloadParams = new URLSearchParams(urlPath.substring(downloadQueryIndex));
-      var downloadPath = downloadParams.get("path");
-      if (!downloadPath) { res.writeHead(400); res.end("Missing path"); return true; }
-      var downloadUserInfo = getOsUserInfoForReq(req);
-      if (osUsers && !downloadUserInfo) { res.writeHead(403); res.end("OS user identity unavailable"); return true; }
-      var downloadFile = resolveFilePath(cwd, downloadPath, safePath, downloadUserInfo);
-      if (!downloadFile) { res.writeHead(403); res.end("Access denied"); return true; }
-
-      try {
-        var downloadContent;
-        if (downloadUserInfo) {
-          downloadContent = fsAsUser("read_binary", { file: downloadFile }, downloadUserInfo).buffer;
-        } else {
-          downloadContent = fs.readFileSync(downloadFile);
-        }
-        var downloadName = path.basename(downloadPath).replace(/[\x00-\x1f\x7f"\\]/g, "_") || "download";
-        var asciiDownloadName = downloadName.replace(/[^\x20-\x7e]/g, "_");
-        var encodedDownloadName = encodeURIComponent(downloadName).replace(/[!'()*]/g, function (character) {
-          return "%" + character.charCodeAt(0).toString(16).toUpperCase();
-        });
-        var contentDisposition = "attachment; filename=\"" + asciiDownloadName + "\"; filename*=UTF-8''" + encodedDownloadName;
-        res.writeHead(200, {
-          "Content-Type": "application/octet-stream",
-          "Content-Length": downloadContent.length,
-          "Content-Disposition": contentDisposition,
-          "Cache-Control": "no-store",
-          "X-Content-Type-Options": "nosniff",
-        });
-        res.end(downloadContent);
-      } catch (e) {
-        res.writeHead(404);
-        res.end("Not found");
-      }
-      return true;
-    }
-
-    // File browser: serve project images
-    if (req.method === "GET" && urlPath.startsWith("/api/file?")) {
-      var qIdx = urlPath.indexOf("?");
-      var params = new URLSearchParams(urlPath.substring(qIdx));
-      var reqFilePath = params.get("path");
-      if (!reqFilePath) { res.writeHead(400); res.end("Missing path"); return true; }
-      if (usersModule.isMultiUser()) {
-        var imageUser = req._clayUser;
-        var imagePermissions = imageUser ? usersModule.getEffectivePermissions(imageUser, osUsers) : null;
-        if (!imagePermissions || !imagePermissions.fileBrowser) {
-          res.writeHead(403, { "Content-Type": "text/plain; charset=utf-8" });
-          res.end("File browser access is not permitted");
-          return true;
-        }
-      }
-      var fileServeUserInfo = getOsUserInfoForReq(req);
-      if (osUsers && !fileServeUserInfo) { res.writeHead(403); res.end("OS user identity unavailable"); return true; }
-      var absFile = resolveFilePath(cwd, reqFilePath, safePath, fileServeUserInfo);
-      if (!absFile) { res.writeHead(403); res.end("Access denied"); return true; }
-      var fileExt = path.extname(absFile).toLowerCase();
-      if (!IMAGE_EXTS.has(fileExt)) { res.writeHead(403); res.end("Only image files"); return true; }
-      try {
-        var fileContent;
-        if (fileServeUserInfo) {
-          var binResult = fsAsUser("read_binary", { file: absFile }, fileServeUserInfo);
-          fileContent = binResult.buffer;
-        } else {
-          fileContent = fs.readFileSync(absFile);
-        }
-        var fileMime = MIME_TYPES[fileExt] || "application/octet-stream";
-        res.writeHead(200, { "Content-Type": fileMime, "Cache-Control": "no-cache" });
-        res.end(fileContent);
-      } catch (e) {
-        res.writeHead(404); res.end("Not found");
-      }
-      return true;
-    }
+    if (fileHTTP.handleHTTP(req, res, urlPath)) return true;
 
     // Skills permission gate
     if (urlPath === "/api/install-skill" || urlPath === "/api/uninstall-skill" || urlPath === "/api/installed-skills") {

package/lib/project-request-access.js

@@ -1,4 +1,5 @@
 // Shared authorization for project requests and long-lived file subscriptions.
+var fileFailure = require("./project-file-path").failure;
 function attachRequestAccess(ctx) {
   var users = ctx.usersModule;
   var opts = ctx.opts || {};
@@ -9,7 +10,7 @@ function attachRequestAccess(ctx) {
 
   function userFor(ws) {
     var user = ws && ws._clayUser;
-    if (user && users.findUserById) return users.findUserById(user.id);
+    if (user && users && users.findUserById) return users.findUserById(user.id);
     return user || null;
   }
 
@@ -53,14 +54,20 @@ function attachRequestAccess(ctx) {
   function osIdentity(ws) {
     if (!ctx.osUsers) return null;
     var user = userFor(ws);
-    if (!user || !user.linuxUser) throw new Error("OS user identity is unavailable");
+    if (!user || !user.linuxUser) throw fileFailure("OS_IDENTITY", "OS user identity is unavailable");
     var info = ctx.getOsUserInfoForWs({ _clayUser: user });
-    if (!info) throw new Error("OS user identity is unavailable");
+    if (!info) throw fileFailure("OS_IDENTITY", "OS user identity is unavailable");
     return info;
   }
 
+  function fileScope(ws) {
+    if (!canUseFiles(ws)) throw fileFailure("FILE_FORBIDDEN", "File browser access is not permitted");
+    var identity = osIdentity(ws);
+    return { identity: identity, projectBound: isMultiUser() && !identity };
+  }
+
   return { permitMessage: permitMessage, canAccessProject: canAccessProject, hasPermission: hasPermission,
-    canUseFiles: canUseFiles, isAdmin: isAdmin, canReadSession: canReadSession, osIdentity: osIdentity };
+    canUseFiles: canUseFiles, isAdmin: isAdmin, canReadSession: canReadSession, osIdentity: osIdentity, fileScope: fileScope };
 }
 
 module.exports = { attachRequestAccess: attachRequestAccess };

package/lib/project.js

@@ -2481,6 +2481,7 @@ function createProjectContext(opts) {
 
   // --- HTTP handler (delegated to project-http.js) ---
   var _http = attachHTTP({
+    requestAccess: _requestAccess,
     cwd: cwd,
     slug: slug,
     project: title || project,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clay-server",
-  "version": "4.3.0",
+  "version": "4.3.1-beta.1",
   "description": "Self-hosted team workspace for Claude Code and Codex. Multi-user, browser-based, with persistent AI mates.",
   "bin": {
     "clay-server": "./bin/cli.js"