@databricks/appkit 0.35.0 → 0.35.2

package/dist/plugins/files/plugin.js

@@ -1,8 +1,9 @@
 import { createLogger } from "../../logging/logger.js";
 import { AuthenticationError } from "../../errors/authentication.js";
 import { init_errors } from "../../errors/index.js";
+import { ServiceContext } from "../../context/service-context.js";
 import { init_user_context, isUserContext } from "../../context/user-context.js";
-import { getCurrentUserId, getExecutionContext, getWorkspaceClient } from "../../context/execution-context.js";
+import { getCurrentUserId, getExecutionContext, getWorkspaceClient, runInUserContext } from "../../context/execution-context.js";
 import { init_context } from "../../context/index.js";
 import { Plugin } from "../../plugin/plugin.js";
 import { ResourceType } from "../../registry/types.generated.js";
@@ -10,8 +11,8 @@ import "../../registry/index.js";
 import { toPlugin } from "../../plugin/to-plugin.js";
 import "../../plugin/index.js";
 import { PolicyDeniedError, policy } from "./policy.js";
-import { contentTypeFromPath, isSafeInlineContentType, validateCustomContentTypes } from "../../connectors/files/defaults.js";
-import { FilesConnector } from "../../connectors/files/client.js";
+import { FILES_MAX_READ_SIZE, contentTypeFromPath, isSafeInlineContentType, validateCustomContentTypes } from "../../connectors/files/defaults.js";
+import { FilesConnector, runWithFilesSpanAttributes } from "../../connectors/files/client.js";
 import "../../connectors/files/index.js";
 import { buildToolkitEntries } from "../../core/agent/build-toolkit.js";
 import { defineTool, executeFromRegistry, toolsFromRegistry } from "../../core/agent/tools/define-tool.js";
@@ -62,6 +63,27 @@ var FilesPlugin = class FilesPlugin extends Plugin {
 	/**
 	* Generates resource requirements dynamically from discovered + configured volumes.
 	* Each volume key maps to a `DATABRICKS_VOLUME_{KEY_UPPERCASE}` env var.
+	*
+	* ## Per-volume permission scope (SP vs OBO)
+	*
+	* The returned manifest entries describe a single permission grant per
+	* volume, but the *grantee* depends on the volume's `auth` setting at
+	* runtime — and that distinction is **not** expressed in the manifest
+	* today:
+	*
+	* - **Service-principal volumes** (the default, `auth: "service-principal"`):
+	*   the app's service principal needs `WRITE_VOLUME` (or read-equivalent)
+	*   on the UC volume. This matches the manifest entry as written.
+	* - **On-behalf-of-user volumes** (`auth: "on-behalf-of-user"`): SDK calls
+	*   execute as the **end user**, so the *user* — not the SP — must hold
+	*   `WRITE_VOLUME` (or read-equivalent) on the UC volume. The SP only
+	*   needs to be allowed to mint user-token requests; it does not need
+	*   direct volume permissions.
+	*
+	* The static manifest cannot currently express this per-volume split, so
+	* callers configuring OBO volumes must communicate the per-user permission
+	* requirement out-of-band (docs, runbooks, deployment scripts) until the
+	* manifest schema gains a per-volume auth scope field.
 	*/
 	static getResourceRequirements(config) {
 		const volumes = FilesPlugin.discoverVolumes(config);
@@ -79,17 +101,65 @@ var FilesPlugin = class FilesPlugin extends Plugin {
 		}));
 	}
 	/**
-	* Extract user identity from the request.
-	* Falls back to `getCurrentUserId()` in development mode.
+	* Extraction for `VolumeHandle.asUser(req)`. In production we require BOTH
+	* `x-forwarded-user` and `x-forwarded-access-token`, and throw
+	* `AuthenticationError.missingToken` if either is missing — otherwise a
+	* request with only `x-forwarded-user: alice` would let policies see Alice
+	* as a "real user" (`isServicePrincipal: false`) while the SDK call below
+	* falls through to the SP client because `_buildUserContextOrNull` returns
+	* `null`. Net effect: policy approves the user, SDK runs as SP, privilege
+	* confusion (CWE-639/863).
+	*
+	* In development (`NODE_ENV === "development"`) we keep a local-loop
+	* convenience: if either header is missing we emit a single warning and
+	* return a policy user explicitly marked `isServicePrincipal: true`, so
+	* even in dev a `usersOnly`-style policy that gates on
+	* `!user.isServicePrincipal` cannot be tricked. The matching SDK execution
+	* path also falls through to the SP client (no `runInUserContext` wrap),
+	* so the policy user and the SDK identity stay aligned.
 	*/
 	_extractUser(req) {
 		const userId = req.header("x-forwarded-user")?.trim();
-		if (userId) return { id: userId };
+		const token = req.header("x-forwarded-access-token")?.trim();
+		if (userId && token) return {
+			id: userId,
+			isServicePrincipal: false
+		};
 		if (process.env.NODE_ENV === "development") {
-			logger.warn("No x-forwarded-user header — falling back to service principal identity for policy checks. Ensure your proxy forwards user headers to test per-user policies.");
-			return { id: getCurrentUserId() };
+			logger.warn("asUser(req) called without complete x-forwarded-user + x-forwarded-access-token headers — falling back to service principal identity (dev mode). In production this request would 401.");
+			return {
+				id: getCurrentUserId(),
+				isServicePrincipal: true
+			};
+		}
+		if (!token) throw AuthenticationError.missingToken("Missing x-forwarded-access-token header for asUser(req). Both x-forwarded-user and x-forwarded-access-token are required.");
+		throw AuthenticationError.missingToken("Missing x-forwarded-user header. Cannot resolve user ID for asUser(req).");
+	}
+	/**
+	* Extraction for OBO (on-behalf-of-user) volumes on the HTTP path. Both the
+	* `x-forwarded-access-token` and `x-forwarded-user` headers must be present
+	* for a valid end-user identity. When the token is missing:
+	* - In production we throw `AuthenticationError.missingToken` so the route
+	*   responds with 401 (no SDK call is made).
+	* - In development (`NODE_ENV === "development"`) we emit a single warning
+	*   and fall back to the service principal identity so local testing
+	*   without a reverse proxy continues to work.
+	*/
+	_extractOboUser(req) {
+		const token = req.header("x-forwarded-access-token")?.trim();
+		const userId = req.header("x-forwarded-user")?.trim();
+		if (token && userId) return {
+			id: userId,
+			isServicePrincipal: false
+		};
+		if (!token && process.env.NODE_ENV === "development") {
+			logger.warn("OBO volume requested without x-forwarded-access-token — falling back to service principal identity (dev mode). In production this request would 401.");
+			return {
+				id: getCurrentUserId(),
+				isServicePrincipal: true
+			};
 		}
-		throw AuthenticationError.missingToken("Missing x-forwarded-user header. Cannot resolve user ID.");
+		throw AuthenticationError.missingToken(!token ? "Missing x-forwarded-access-token header for on-behalf-of-user volume." : "Missing x-forwarded-user header for on-behalf-of-user volume.");
 	}
 	/**
 	* Check the policy for a volume. No-op if no policy is configured.
@@ -110,17 +180,43 @@ var FilesPlugin = class FilesPlugin extends Plugin {
 	}
 	/**
 	* HTTP-level wrapper around `_checkPolicy`.
-	* Extracts user (401 on failure), runs policy (403 on denial).
+	* Selects the policy user based on the volume's auth mode (resolved via
+	* `_resolveAuth`):
+	* - `"service-principal"` (default): use the `x-forwarded-user` header when
+	*   present, otherwise fall back to the SP identity (legacy behavior).
+	* - `"on-behalf-of-user"`: require `x-forwarded-access-token` (and the
+	*   matching `x-forwarded-user`); 401 in production when missing,
+	*   dev-fallback to SP identity in development.
+	* Then runs the volume policy (403 on denial, 500 on unexpected error).
 	* Returns `true` if the request may proceed, `false` if a response was sent.
+	*
+	* NOTE: This method only selects which identity the *policy* sees. The
+	* matching SDK execution identity is selected separately by
+	* `_resolveAuthForRequest` and applied via `_runWithAuth` /
+	* `runInUserContext` in each handler. The two selections are designed to
+	* converge on the same identity per the policy-user matrix in the docs —
+	* see `docs/docs/plugins/files.md#policy-user-matrix`.
 	*/
 	async _enforcePolicy(req, res, volumeKey, action, path, resourceOverrides) {
 		let user;
 		try {
-			user = this._extractUser(req);
+			if (this._resolveAuth(volumeKey) === "on-behalf-of-user") user = this._extractOboUser(req);
+			else {
+				const headerUserId = req.header("x-forwarded-user")?.trim();
+				if (headerUserId) user = { id: headerUserId };
+				else {
+					logger.debug("No x-forwarded-user header — proceeding with service principal identity for policy evaluation.");
+					user = {
+						id: getCurrentUserId(),
+						isServicePrincipal: true
+					};
+				}
+			}
 		} catch (error) {
 			if (error instanceof AuthenticationError) {
+				logger.warn("Authentication failed during policy evaluation for volume %s: %O", volumeKey, error);
 				res.status(401).json({
-					error: error.message,
+					error: "Unauthorized",
 					plugin: this.name
 				});
 				return false;
@@ -158,8 +254,10 @@ var FilesPlugin = class FilesPlugin extends Plugin {
 			const volumePath = process.env[envVar];
 			const mergedConfig = {
 				maxUploadSize: volumeCfg.maxUploadSize ?? config.maxUploadSize,
+				maxReadSize: volumeCfg.maxReadSize ?? config.maxReadSize,
 				customContentTypes: volumeCfg.customContentTypes ?? config.customContentTypes,
-				policy: volumeCfg.policy ?? policy.publicRead()
+				policy: volumeCfg.policy ?? policy.publicRead(),
+				auth: volumeCfg.auth
 			};
 			this.volumeConfigs[key] = mergedConfig;
 			this.volumeConnectors[key] = new FilesConnector({
@@ -169,7 +267,7 @@ var FilesPlugin = class FilesPlugin extends Plugin {
 				customContentTypes: mergedConfig.customContentTypes
 			});
 			Object.assign(this.tools, this._defineVolumeTools(key));
-			if (!volumeCfg.policy) logger.warn("Volume \"%s\" has no explicit policy — defaulting to publicRead(). Set a policy in files({ volumes: { %s: { policy: ... } } }) to silence this warning.", key, key);
+			if (!volumeCfg.policy) logger.warn("Volume \"%s\" has no explicit policy — defaulting to publicRead(). This also matches header-less HTTP requests (which run as the service principal). Set a policy in files({ volumes: { %s: { policy: ... } } }) to silence this warning.", key, key);
 		}
 	}
 	injectRoutes(router) {
@@ -307,6 +405,27 @@ var FilesPlugin = class FilesPlugin extends Plugin {
 		};
 	}
 	/**
+	* Extract `req.query.path` as a single string when present.
+	*
+	* Express coerces repeated query parameters (`?path=a&path=b`) to a string
+	* array and dotted/nested params (`?path[k]=v`) to an object. Reject those
+	* with `400` instead of letting non-string values reach `_isValidPath` /
+	* `connector.resolvePath`, which would misbehave on arrays or objects.
+	*
+	* Returns `{ path }` (with `path` either a string or `undefined` when the
+	* query parameter was absent) on success. Returns `undefined` and writes a
+	* `400` response when the value is not a single string — callers must
+	* check the return for `undefined` before continuing.
+	*/
+	_readPathQuery(req, res) {
+		const value = req.query.path;
+		if (value === void 0 || typeof value === "string") return { path: value };
+		res.status(400).json({
+			error: "path query parameter must be a single string",
+			plugin: this.name
+		});
+	}
+	/**
 	* Validate a file/directory path from user input.
 	* Returns `true` if valid, or an error message string if invalid.
 	*/
@@ -316,29 +435,104 @@ var FilesPlugin = class FilesPlugin extends Plugin {
 		if (path.includes("\0")) return "path must not contain null bytes";
 		return true;
 	}
-	_readSettings(cacheKey) {
+	_readSettings(cacheKey, authMode) {
+		const cache = authMode === "on-behalf-of-user" ? {
+			...FILES_READ_DEFAULTS.cache,
+			enabled: false,
+			cacheKey
+		} : {
+			...FILES_READ_DEFAULTS.cache,
+			cacheKey
+		};
 		return { default: {
 			...FILES_READ_DEFAULTS,
-			cache: {
-				...FILES_READ_DEFAULTS.cache,
-				cacheKey
-			}
+			cache,
+			telemetryInterceptor: { attributes: this._authModeAttributes(authMode) }
+		} };
+	}
+	_writeSettings(authMode) {
+		return { default: {
+			...FILES_WRITE_DEFAULTS,
+			telemetryInterceptor: { attributes: this._authModeAttributes(authMode) }
+		} };
+	}
+	_downloadSettings(authMode) {
+		return { default: {
+			...FILES_DOWNLOAD_DEFAULTS,
+			telemetryInterceptor: { attributes: this._authModeAttributes(authMode) }
 		} };
 	}
 	/**
 	* Invalidate cached list entries for a directory after a write operation.
-	* Uses the same cache-key format as `_handleList`: resolved path for
-	* subdirectories, `"__root__"` for the volume root.
+	* Must produce the SAME cache-key shape that `_handleList` stored under.
+	* `_handleList` builds its key from `req.query.path`: when `path` is
+	* provided it uses `connector.resolvePath(path)`, otherwise it uses the
+	* sentinel `"__root__"`. The invalidation here must derive the matching
+	* directory from the FILE path being written:
+	*
+	* - `"/Volumes/c/s/v/foo/bar.txt"` → `parentDirectory` returns
+	*   `"/Volumes/c/s/v/foo"` → resolved path key.
+	* - `"/bar.txt"` and `"bar.txt"` → root-level files: matching list cache
+	*   was a rootless `list()` call → `"__root__"` sentinel.
+	* - `"/Volumes/c/s/v/bar.txt"` → `parentDirectory` returns the UC
+	*   volume path (`"/Volumes/c/s/v"`). That's also root-level — a
+	*   rootless `list()` would have cached under `"__root__"`, while
+	*   `list("/Volumes/c/s/v")` and `list("/Volumes/c/s/v/")` would have
+	*   cached under the volume path with and without trailing slash. All
+	*   three are invalidated.
 	*
-	* Cache keys include `getCurrentUserId()` — must match the identity used
-	* by `this.execute()` in `_handleList`. Both run in service-principal
-	* context; wrapping either in `runInUserContext` would break invalidation.
+	* On OBO volumes the read cache is disabled (see `_readSettings`), so
+	* invalidation is a no-op here for `mode === "on-behalf-of-user"`. The
+	* cache layer is keyed by `getCurrentUserId()`, so user A's writes can
+	* only invalidate user A's cache entry — user B would otherwise see stale
+	* data for the same volume/path until TTL. Disabling the cache on OBO
+	* trades read performance for correctness; the alternative is a
+	* per-(volume, path) generation counter folded into the cache key on
+	* writes (a future enhancement).
+	*
+	* Best-effort: a thrown `connector.resolvePath` (e.g. on malformed input)
+	* is swallowed here. Invalidation is purely an optimization signal — a
+	* missed delete only costs read freshness, not correctness, and
+	* propagating the error would convert a successful write into an HTTP
+	* 500.
+	*
+	* Returns a `Promise<void>`; callers MUST `await` this before sending the
+	* HTTP success response so a follow-up `GET /list` issued in the same tick
+	* cannot race the underlying `cache.delete()` and observe stale data.
 	*/
-	_invalidateListCache(volumeKey, parentPath, connector) {
-		const parent = parentDirectory(parentPath);
-		const cachePathSegment = parent ? connector.resolvePath(parent) : "__root__";
-		const listKey = this.cache.generateKey([`files:${volumeKey}:list`, cachePathSegment], getCurrentUserId());
-		this.cache.delete(listKey);
+	async _invalidateListCache(volumeKey, writtenPath, connector, mode = "service-principal") {
+		if (mode === "on-behalf-of-user") return;
+		const parent = parentDirectory(writtenPath);
+		const userKey = getCurrentUserId();
+		const tryDelete = async (segment) => {
+			try {
+				await this.cache.delete(this.cache.generateKey([`files:${volumeKey}:list`, segment], userKey));
+			} catch (err) {
+				logger.debug("List-cache invalidation failed for volume=%s segment=%s: %O", volumeKey, segment, err);
+			}
+		};
+		let volumeRoot = null;
+		try {
+			volumeRoot = connector.resolvePath("").replace(/\/+$/, "");
+		} catch (err) {
+			logger.debug("List-cache invalidation: resolvePath(\"\") failed for volume=%s: %O", volumeKey, err);
+		}
+		if (!parent || parent === "/" || volumeRoot !== null && parent === volumeRoot) {
+			await tryDelete("__root__");
+			if (volumeRoot !== null) {
+				await tryDelete(volumeRoot);
+				await tryDelete(`${volumeRoot}/`);
+			}
+			return;
+		}
+		let resolved;
+		try {
+			resolved = connector.resolvePath(parent);
+		} catch (err) {
+			logger.debug("List-cache invalidation: resolvePath(%s) failed for volume=%s: %O", parent, volumeKey, err);
+			return;
+		}
+		await tryDelete(resolved);
 	}
 	_handleApiError(res, error, fallbackMessage) {
 		if (error instanceof PolicyDeniedError) {
@@ -349,8 +543,9 @@ var FilesPlugin = class FilesPlugin extends Plugin {
 			return;
 		}
 		if (error instanceof AuthenticationError) {
+			logger.warn("Authentication failed in %s: %O", this.name, error);
 			res.status(401).json({
-				error: error.message,
+				error: "Unauthorized",
 				plugin: this.name
 			});
 			return;
@@ -358,8 +553,9 @@ var FilesPlugin = class FilesPlugin extends Plugin {
 		if (error instanceof ApiError) {
 			const status = error.statusCode ?? 500;
 			if (status >= 400 && status < 500) {
+				logger.warn("Upstream %d in %s: %O", status, this.name, error);
 				res.status(status).json({
-					error: error.message,
+					error: STATUS_CODES[status] ?? "Client Error",
 					statusCode: status,
 					plugin: this.name
 				});
@@ -385,22 +581,29 @@ var FilesPlugin = class FilesPlugin extends Plugin {
 		});
 	}
 	async _handleList(req, res, connector, volumeKey) {
-		const path = req.query.path;
+		const query = this._readPathQuery(req, res);
+		if (!query) return;
+		const path = query.path;
 		if (!await this._enforcePolicy(req, res, volumeKey, "list", path ?? "/")) return;
-		try {
-			const result = await this.execute(async () => connector.list(getWorkspaceClient(), path), this._readSettings([`files:${volumeKey}:list`, path ? connector.resolvePath(path) : "__root__"]));
-			if (!result.ok) {
-				this._sendStatusError(res, result.status);
-				return;
+		const { mode, userCtx } = this._resolveAuthForRequest(req, volumeKey);
+		await this._runWithAuth(userCtx, async () => {
+			try {
+				const result = await this.execute(async () => connector.list(getWorkspaceClient(), path), this._readSettings([`files:${volumeKey}:list`, path ? connector.resolvePath(path) : "__root__"], mode));
+				if (!result.ok) {
+					this._sendStatusError(res, result.status);
+					return;
+				}
+				res.json(result.data);
+			} catch (error) {
+				this._handleApiError(res, error, "List failed");
 			}
-			res.json(result.data);
-		} catch (error) {
-			this._handleApiError(res, error, "List failed");
-		}
+		});
 	}
 	async _handleRead(req, res, connector, volumeKey) {
-		const path = req.query.path;
-		const valid = this._isValidPath(path);
+		const query = this._readPathQuery(req, res);
+		if (!query) return;
+		const rawPath = query.path;
+		const valid = this._isValidPath(rawPath);
 		if (valid !== true) {
 			res.status(400).json({
 				error: valid,
@@ -408,17 +611,51 @@ var FilesPlugin = class FilesPlugin extends Plugin {
 			});
 			return;
 		}
+		const path = rawPath;
 		if (!await this._enforcePolicy(req, res, volumeKey, "read", path)) return;
-		try {
-			const result = await this.execute(async () => connector.read(getWorkspaceClient(), path), this._readSettings([`files:${volumeKey}:read`, connector.resolvePath(path)]));
-			if (!result.ok) {
-				this._sendStatusError(res, result.status);
-				return;
+		const maxReadSize = this.volumeConfigs[volumeKey].maxReadSize ?? FILES_MAX_READ_SIZE;
+		const { mode, userCtx } = this._resolveAuthForRequest(req, volumeKey);
+		await this._runWithAuth(userCtx, async () => {
+			try {
+				const response = await this.execute(async () => connector.download(getWorkspaceClient(), path), this._downloadSettings(mode));
+				if (!response.ok) {
+					this._sendStatusError(res, response.status);
+					return;
+				}
+				if (!response.data.contents) {
+					res.type("text/plain").send("");
+					return;
+				}
+				const reader = response.data.contents.getReader();
+				const chunks = [];
+				let bytesRead = 0;
+				try {
+					while (true) {
+						const { value, done } = await reader.read();
+						if (done) break;
+						bytesRead += value.byteLength;
+						if (bytesRead > maxReadSize) {
+							res.status(413).json({
+								error: `File exceeds maxReadSize (${maxReadSize} bytes). Use /download for large files.`,
+								plugin: this.name
+							});
+							try {
+								await reader.cancel();
+							} catch {}
+							return;
+						}
+						chunks.push(value);
+					}
+				} finally {
+					try {
+						reader.releaseLock();
+					} catch {}
+				}
+				res.type("text/plain").send(Buffer.concat(chunks, bytesRead));
+			} catch (error) {
+				this._handleApiError(res, error, "Read failed");
 			}
-			res.type("text/plain").send(result.data);
-		} catch (error) {
-			this._handleApiError(res, error, "Read failed");
-		}
+		});
 	}
 	async _handleDownload(req, res, connector, volumeKey) {
 		return this._serveFile(req, res, connector, volumeKey, { mode: "download" });
@@ -432,8 +669,10 @@ var FilesPlugin = class FilesPlugin extends Plugin {
 	* - `raw`: adds CSP sandbox; forces attachment only for unsafe content types.
 	*/
 	async _serveFile(req, res, connector, volumeKey, opts) {
-		const path = req.query.path;
-		const valid = this._isValidPath(path);
+		const query = this._readPathQuery(req, res);
+		if (!query) return;
+		const rawPath = query.path;
+		const valid = this._isValidPath(rawPath);
 		if (valid !== true) {
 			res.status(400).json({
 				error: valid,
@@ -441,40 +680,46 @@ var FilesPlugin = class FilesPlugin extends Plugin {
 			});
 			return;
 		}
+		const path = rawPath;
 		if (!await this._enforcePolicy(req, res, volumeKey, opts.mode, path)) return;
 		const label = opts.mode === "download" ? "Download" : "Raw fetch";
 		const volumeCfg = this.volumeConfigs[volumeKey];
-		try {
-			const settings = { default: FILES_DOWNLOAD_DEFAULTS };
-			const response = await this.execute(async () => connector.download(getWorkspaceClient(), path), settings);
-			if (!response.ok) {
-				this._sendStatusError(res, response.status);
-				return;
+		const { mode, userCtx } = this._resolveAuthForRequest(req, volumeKey);
+		await this._runWithAuth(userCtx, async () => {
+			try {
+				const settings = this._downloadSettings(mode);
+				const response = await this.execute(async () => connector.download(getWorkspaceClient(), path), settings);
+				if (!response.ok) {
+					this._sendStatusError(res, response.status);
+					return;
+				}
+				const resolvedType = contentTypeFromPath(path, void 0, volumeCfg.customContentTypes);
+				const fileName = sanitizeFilename(path.split("/").pop() ?? "download");
+				res.setHeader("Content-Type", resolvedType);
+				res.setHeader("X-Content-Type-Options", "nosniff");
+				if (opts.mode === "raw") {
+					res.setHeader("Content-Security-Policy", "sandbox");
+					if (!isSafeInlineContentType(resolvedType)) res.setHeader("Content-Disposition", `attachment; filename="${fileName}"`);
+				} else res.setHeader("Content-Disposition", `attachment; filename="${fileName}"`);
+				if (response.data.contents) {
+					const nodeStream = Readable.fromWeb(response.data.contents);
+					nodeStream.on("error", (err) => {
+						logger.error("Stream error during %s: %O", opts.mode, err);
+						if (!res.headersSent) this._sendStatusError(res, 500);
+						else res.destroy();
+					});
+					nodeStream.pipe(res);
+				} else res.end();
+			} catch (error) {
+				this._handleApiError(res, error, `${label} failed`);
 			}
-			const resolvedType = contentTypeFromPath(path, void 0, volumeCfg.customContentTypes);
-			const fileName = sanitizeFilename(path.split("/").pop() ?? "download");
-			res.setHeader("Content-Type", resolvedType);
-			res.setHeader("X-Content-Type-Options", "nosniff");
-			if (opts.mode === "raw") {
-				res.setHeader("Content-Security-Policy", "sandbox");
-				if (!isSafeInlineContentType(resolvedType)) res.setHeader("Content-Disposition", `attachment; filename="${fileName}"`);
-			} else res.setHeader("Content-Disposition", `attachment; filename="${fileName}"`);
-			if (response.data.contents) {
-				const nodeStream = Readable.fromWeb(response.data.contents);
-				nodeStream.on("error", (err) => {
-					logger.error("Stream error during %s: %O", opts.mode, err);
-					if (!res.headersSent) this._sendStatusError(res, 500);
-					else res.destroy();
-				});
-				nodeStream.pipe(res);
-			} else res.end();
-		} catch (error) {
-			this._handleApiError(res, error, `${label} failed`);
-		}
+		});
 	}
 	async _handleExists(req, res, connector, volumeKey) {
-		const path = req.query.path;
-		const valid = this._isValidPath(path);
+		const query = this._readPathQuery(req, res);
+		if (!query) return;
+		const rawPath = query.path;
+		const valid = this._isValidPath(rawPath);
 		if (valid !== true) {
 			res.status(400).json({
 				error: valid,
@@ -482,21 +727,27 @@ var FilesPlugin = class FilesPlugin extends Plugin {
 			});
 			return;
 		}
+		const path = rawPath;
 		if (!await this._enforcePolicy(req, res, volumeKey, "exists", path)) return;
-		try {
-			const result = await this.execute(async () => connector.exists(getWorkspaceClient(), path), this._readSettings([`files:${volumeKey}:exists`, connector.resolvePath(path)]));
-			if (!result.ok) {
-				this._sendStatusError(res, result.status);
-				return;
+		const { mode, userCtx } = this._resolveAuthForRequest(req, volumeKey);
+		await this._runWithAuth(userCtx, async () => {
+			try {
+				const result = await this.execute(async () => connector.exists(getWorkspaceClient(), path), this._readSettings([`files:${volumeKey}:exists`, connector.resolvePath(path)], mode));
+				if (!result.ok) {
+					this._sendStatusError(res, result.status);
+					return;
+				}
+				res.json({ exists: result.data });
+			} catch (error) {
+				this._handleApiError(res, error, "Exists check failed");
 			}
-			res.json({ exists: result.data });
-		} catch (error) {
-			this._handleApiError(res, error, "Exists check failed");
-		}
+		});
 	}
 	async _handleMetadata(req, res, connector, volumeKey) {
-		const path = req.query.path;
-		const valid = this._isValidPath(path);
+		const query = this._readPathQuery(req, res);
+		if (!query) return;
+		const rawPath = query.path;
+		const valid = this._isValidPath(rawPath);
 		if (valid !== true) {
 			res.status(400).json({
 				error: valid,
@@ -504,21 +755,27 @@ var FilesPlugin = class FilesPlugin extends Plugin {
 			});
 			return;
 		}
+		const path = rawPath;
 		if (!await this._enforcePolicy(req, res, volumeKey, "metadata", path)) return;
-		try {
-			const result = await this.execute(async () => connector.metadata(getWorkspaceClient(), path), this._readSettings([`files:${volumeKey}:metadata`, connector.resolvePath(path)]));
-			if (!result.ok) {
-				this._sendStatusError(res, result.status);
-				return;
+		const { mode, userCtx } = this._resolveAuthForRequest(req, volumeKey);
+		await this._runWithAuth(userCtx, async () => {
+			try {
+				const result = await this.execute(async () => connector.metadata(getWorkspaceClient(), path), this._readSettings([`files:${volumeKey}:metadata`, connector.resolvePath(path)], mode));
+				if (!result.ok) {
+					this._sendStatusError(res, result.status);
+					return;
+				}
+				res.json(result.data);
+			} catch (error) {
+				this._handleApiError(res, error, "Metadata fetch failed");
 			}
-			res.json(result.data);
-		} catch (error) {
-			this._handleApiError(res, error, "Metadata fetch failed");
-		}
+		});
 	}
 	async _handlePreview(req, res, connector, volumeKey) {
-		const path = req.query.path;
-		const valid = this._isValidPath(path);
+		const query = this._readPathQuery(req, res);
+		if (!query) return;
+		const rawPath = query.path;
+		const valid = this._isValidPath(rawPath);
 		if (valid !== true) {
 			res.status(400).json({
 				error: valid,
@@ -526,21 +783,27 @@ var FilesPlugin = class FilesPlugin extends Plugin {
 			});
 			return;
 		}
+		const path = rawPath;
 		if (!await this._enforcePolicy(req, res, volumeKey, "preview", path)) return;
-		try {
-			const result = await this.execute(async () => connector.preview(getWorkspaceClient(), path), this._readSettings([`files:${volumeKey}:preview`, connector.resolvePath(path)]));
-			if (!result.ok) {
-				this._sendStatusError(res, result.status);
-				return;
+		const { mode, userCtx } = this._resolveAuthForRequest(req, volumeKey);
+		await this._runWithAuth(userCtx, async () => {
+			try {
+				const result = await this.execute(async () => connector.preview(getWorkspaceClient(), path), this._readSettings([`files:${volumeKey}:preview`, connector.resolvePath(path)], mode));
+				if (!result.ok) {
+					this._sendStatusError(res, result.status);
+					return;
+				}
+				res.json(result.data);
+			} catch (error) {
+				this._handleApiError(res, error, "Preview failed");
 			}
-			res.json(result.data);
-		} catch (error) {
-			this._handleApiError(res, error, "Preview failed");
-		}
+		});
 	}
 	async _handleUpload(req, res, connector, volumeKey) {
-		const path = req.query.path;
-		const valid = this._isValidPath(path);
+		const query = this._readPathQuery(req, res);
+		if (!query) return;
+		const rawPath = query.path;
+		const valid = this._isValidPath(rawPath);
 		if (valid !== true) {
 			res.status(400).json({
 				error: valid,
@@ -548,6 +811,7 @@ var FilesPlugin = class FilesPlugin extends Plugin {
 			});
 			return;
 		}
+		const path = rawPath;
 		const maxSize = this.volumeConfigs[volumeKey].maxUploadSize ?? FILES_MAX_UPLOAD_SIZE;
 		const rawContentLength = req.headers["content-length"];
 		let contentLength;
@@ -570,41 +834,48 @@ var FilesPlugin = class FilesPlugin extends Plugin {
 			return;
 		}
 		logger.debug(req, "Upload started: volume=%s path=%s", volumeKey, path);
-		try {
-			const rawStream = Readable.toWeb(req);
-			let bytesReceived = 0;
-			const webStream = rawStream.pipeThrough(new TransformStream({ transform(chunk, controller) {
-				bytesReceived += chunk.byteLength;
-				if (bytesReceived > maxSize) {
-					controller.error(/* @__PURE__ */ new Error(`Upload stream exceeds maximum allowed size (${maxSize} bytes)`));
+		const { mode, userCtx } = this._resolveAuthForRequest(req, volumeKey);
+		await this._runWithAuth(userCtx, async () => {
+			try {
+				const rawStream = Readable.toWeb(req);
+				let bytesReceived = 0;
+				const webStream = rawStream.pipeThrough(new TransformStream({ transform(chunk, controller) {
+					bytesReceived += chunk.byteLength;
+					if (bytesReceived > maxSize) {
+						controller.error(/* @__PURE__ */ new Error(`Upload stream exceeds maximum allowed size (${maxSize} bytes)`));
+						return;
+					}
+					if (contentLength !== void 0 && bytesReceived > contentLength) {
+						controller.error(/* @__PURE__ */ new Error(`Upload stream exceeds declared Content-Length (${contentLength} bytes)`));
+						return;
+					}
+					controller.enqueue(chunk);
+				} }));
+				logger.debug(req, "Upload body received: volume=%s path=%s, size=%d bytes", volumeKey, path, contentLength ?? 0);
+				const settings = this._writeSettings(mode);
+				const result = await this.trackWrite(() => this.execute(async () => {
+					await connector.upload(getWorkspaceClient(), path, webStream);
+					return { success: true };
+				}, settings));
+				await this._invalidateListCache(volumeKey, path, connector, mode);
+				if (!result.ok) {
+					logger.error(req, "Upload failed: volume=%s path=%s, size=%d bytes", volumeKey, path, contentLength ?? 0);
+					this._sendStatusError(res, result.status);
 					return;
 				}
-				controller.enqueue(chunk);
-			} }));
-			logger.debug(req, "Upload body received: volume=%s path=%s, size=%d bytes", volumeKey, path, contentLength ?? 0);
-			const settings = { default: FILES_WRITE_DEFAULTS };
-			const result = await this.trackWrite(() => this.execute(async () => {
-				await connector.upload(getWorkspaceClient(), path, webStream);
-				return { success: true };
-			}, settings));
-			this._invalidateListCache(volumeKey, path, connector);
-			if (!result.ok) {
-				logger.error(req, "Upload failed: volume=%s path=%s, size=%d bytes", volumeKey, path, contentLength ?? 0);
-				this._sendStatusError(res, result.status);
-				return;
-			}
-			logger.debug(req, "Upload complete: volume=%s path=%s", volumeKey, path);
-			res.json(result.data);
-		} catch (error) {
-			if (error instanceof Error && error.message.includes("exceeds maximum allowed size")) {
-				res.status(413).json({
-					error: error.message,
-					plugin: this.name
-				});
-				return;
+				logger.debug(req, "Upload complete: volume=%s path=%s", volumeKey, path);
+				res.json(result.data);
+			} catch (error) {
+				if (error instanceof Error && (error.message.includes("exceeds maximum allowed size") || error.message.includes("exceeds declared Content-Length"))) {
+					res.status(413).json({
+						error: error.message,
+						plugin: this.name
+					});
+					return;
+				}
+				this._handleApiError(res, error, "Upload failed");
 			}
-			this._handleApiError(res, error, "Upload failed");
-		}
+		});
 	}
 	async _handleMkdir(req, res, connector, volumeKey) {
 		const dirPath = typeof req.body?.path === "string" ? req.body.path : void 0;
@@ -617,24 +888,29 @@ var FilesPlugin = class FilesPlugin extends Plugin {
 			return;
 		}
 		if (!await this._enforcePolicy(req, res, volumeKey, "mkdir", dirPath)) return;
-		try {
-			const settings = { default: FILES_WRITE_DEFAULTS };
-			const result = await this.trackWrite(() => this.execute(async () => {
-				await connector.createDirectory(getWorkspaceClient(), dirPath);
-				return { success: true };
-			}, settings));
-			this._invalidateListCache(volumeKey, dirPath, connector);
-			if (!result.ok) {
-				this._sendStatusError(res, result.status);
-				return;
+		const { mode, userCtx } = this._resolveAuthForRequest(req, volumeKey);
+		await this._runWithAuth(userCtx, async () => {
+			try {
+				const settings = this._writeSettings(mode);
+				const result = await this.trackWrite(() => this.execute(async () => {
+					await connector.createDirectory(getWorkspaceClient(), dirPath);
+					return { success: true };
+				}, settings));
+				await this._invalidateListCache(volumeKey, dirPath, connector, mode);
+				if (!result.ok) {
+					this._sendStatusError(res, result.status);
+					return;
+				}
+				res.json(result.data);
+			} catch (error) {
+				this._handleApiError(res, error, "Create directory failed");
 			}
-			res.json(result.data);
-		} catch (error) {
-			this._handleApiError(res, error, "Create directory failed");
-		}
+		});
 	}
 	async _handleDelete(req, res, connector, volumeKey) {
-		const rawPath = req.query.path;
+		const query = this._readPathQuery(req, res);
+		if (!query) return;
+		const rawPath = query.path;
 		const valid = this._isValidPath(rawPath);
 		if (valid !== true) {
 			res.status(400).json({
@@ -645,36 +921,177 @@ var FilesPlugin = class FilesPlugin extends Plugin {
 		}
 		const path = rawPath;
 		if (!await this._enforcePolicy(req, res, volumeKey, "delete", path)) return;
-		try {
-			const settings = { default: FILES_WRITE_DEFAULTS };
-			const result = await this.trackWrite(() => this.execute(async () => {
-				await connector.delete(getWorkspaceClient(), path);
-				return { success: true };
-			}, settings));
-			this._invalidateListCache(volumeKey, path, connector);
-			if (!result.ok) {
-				this._sendStatusError(res, result.status);
-				return;
+		const { mode, userCtx } = this._resolveAuthForRequest(req, volumeKey);
+		await this._runWithAuth(userCtx, async () => {
+			try {
+				const settings = this._writeSettings(mode);
+				const result = await this.trackWrite(() => this.execute(async () => {
+					await connector.delete(getWorkspaceClient(), path);
+					return { success: true };
+				}, settings));
+				await this._invalidateListCache(volumeKey, path, connector, mode);
+				if (!result.ok) {
+					this._sendStatusError(res, result.status);
+					return;
+				}
+				res.json(result.data);
+			} catch (error) {
+				this._handleApiError(res, error, "Delete failed");
 			}
-			res.json(result.data);
-		} catch (error) {
-			this._handleApiError(res, error, "Delete failed");
-		}
+		});
+	}
+	_resolveAuth(volumeKey) {
+		return this.volumeConfigs[volumeKey]?.auth ?? this.config.auth ?? "service-principal";
 	}
 	/**
-	* Creates a VolumeAPI for a specific volume key.
+	* Build a `UserContext` from request headers when both
+	* `x-forwarded-access-token` and `x-forwarded-user` are present, otherwise
+	* return `null`. Used by OBO route handlers to wrap SDK calls in the
+	* end-user's identity. A `null` result means "fall back to the service
+	* principal client" — for OBO volumes in production, `_enforcePolicy` will
+	* already have responded 401 before we get here, so `null` is reachable
+	* only on the dev-fallback path.
+	*/
+	_buildUserContextOrNull(req) {
+		const token = req.header("x-forwarded-access-token")?.trim();
+		const userId = req.header("x-forwarded-user")?.trim();
+		if (!token || !userId) return null;
+		return ServiceContext.createUserContext(token, userId);
+	}
+	/**
+	* Build the telemetry attribute hash for the `files.auth_mode` span
+	* attribute. The value reflects what operationally happened — i.e.
+	* whether `runInUserContext` actually wrapped the SDK call:
+	* - HTTP route on OBO volume + valid token → `"on-behalf-of-user"`.
+	* - HTTP route on OBO volume + dev-fallback (no token) →
+	*   `"service-principal"` (the route falls through to the SP client).
+	* - HTTP route on SP volume → `"service-principal"`.
+	* - `asUser(req)` programmatic calls with a real user context →
+	*   `"on-behalf-of-user"`.
+	* - Any unwrapped path → `"service-principal"`.
+	*/
+	_authModeAttributes(authMode) {
+		return { "files.auth_mode": authMode };
+	}
+	/**
+	* One-shot resolver for HTTP route handlers. Builds the request's
+	* `UserContext` AT MOST ONCE (when the volume is OBO and the headers are
+	* present) and returns both the operationally-effective auth mode and the
+	* pre-built `UserContext`.
 	*
-	* By default, enforces the volume's policy before each operation.
-	* Pass `bypassPolicy: true` to skip policy checks — useful for
-	* background jobs or migrations that should bypass user-facing policies.
+	* Handlers thread the `userCtx` into `_runWithAuth(userCtx, fn)` to avoid
+	* a second `ServiceContext.createUserContext()` allocation — that call
+	* builds a fresh `WorkspaceClient` per invocation, so doing it twice per
+	* request was pure throwaway overhead.
+	*/
+	_resolveAuthForRequest(req, volumeKey) {
+		if (this._resolveAuth(volumeKey) !== "on-behalf-of-user") return {
+			mode: "service-principal",
+			userCtx: null
+		};
+		const userCtx = this._buildUserContextOrNull(req);
+		return userCtx ? {
+			mode: "on-behalf-of-user",
+			userCtx
+		} : {
+			mode: "service-principal",
+			userCtx: null
+		};
+	}
+	/**
+	* Run `fn` under the correct execution context.
+	* - `userCtx` is `null`: invokes `fn` directly so the service-principal
+	*   `WorkspaceClient` and `getCurrentUserId()` are used — identical
+	*   behavior to pre-OBO releases. This covers both SP volumes and the
+	*   OBO dev-fallback path (where headers were missing).
+	* - `userCtx` is a `UserContext`: wraps `fn` in `runInUserContext(userCtx)`,
+	*   so SDK calls execute as the end user and `getCurrentUserId()` (and
+	*   therefore cache keys) resolve to the user's ID.
 	*
-	* @security When `bypassPolicy` is `true`, no policy enforcement runs.
-	* Do not expose bypassed APIs to HTTP routes or end-user code paths.
+	* The caller is responsible for building `userCtx` exactly once per
+	* request via `_resolveAuthForRequest`; this signature deliberately does
+	* NOT take a `req` so it cannot accidentally re-build the context.
 	*/
-	createVolumeAPI(volumeKey, user, options) {
+	async _runWithAuth(userCtx, fn) {
+		if (userCtx) return runInUserContext(userCtx, fn);
+		return fn();
+	}
+	/**
+	* Tag the span that `FilesConnector.<operation>` opens with
+	* `files.auth_mode`. Programmatic VolumeAPI methods bypass
+	* `this.execute(...)` (and therefore the `TelemetryInterceptor`), so the
+	* connector's own `files.<operation>` span is the natural place to land
+	* this attribute. Rather than opening a parent `files.<operation>` span
+	* (which would duplicate the connector's span — same name, doubled
+	* allocation/export), we propagate the attribute via AsyncLocalStorage
+	* and let the connector merge it into its existing span at creation
+	* time.
+	*
+	* The `operation` parameter is unused by the propagation mechanism (the
+	* connector knows its own operation), but kept in the signature for API
+	* stability with the previous span-creation form.
+	*/
+	_withAuthModeAttributes(_operation, authMode, fn) {
+		return runWithFilesSpanAttributes(this._authModeAttributes(authMode), fn);
+	}
+	/**
+	* Wrap each `VolumeAPI` method so the `FilesConnector` span it produces is
+	* tagged with `files.auth_mode = "service-principal"`. Used for
+	* programmatic calls that don't go through `asUser(req)`.
+	*
+	* The attribute is attached to the connector's existing span via
+	* AsyncLocalStorage propagation (see `_withAuthModeAttributes`); no
+	* additional parent span is opened, so each call produces exactly one
+	* `files.<operation>` span instead of two.
+	*/
+	_wrapVolumeAPIWithSPSpan(api) {
+		const wrap = (operation, fn) => (...args) => this._withAuthModeAttributes(operation, "service-principal", () => fn(...args));
+		return {
+			list: wrap("list", api.list),
+			read: wrap("read", api.read),
+			download: wrap("download", api.download),
+			exists: wrap("exists", api.exists),
+			metadata: wrap("metadata", api.metadata),
+			upload: wrap("upload", api.upload),
+			createDirectory: wrap("createDirectory", api.createDirectory),
+			delete: wrap("delete", api.delete),
+			preview: wrap("preview", api.preview)
+		};
+	}
+	/**
+	* Wrap each `VolumeAPI` method so its execution runs inside
+	* `runInUserContext(userCtx, ...)`. Used by `VolumeHandle.asUser(req)` to
+	* force the SDK identity to the end user regardless of the volume's
+	* `auth` setting. The policy check baked into each method (via
+	* `createVolumeAPI`) runs inside the same scope, so `getCurrentUserId()`
+	* and any cache `userKey` derived from it also resolve to the user.
+	*
+	* Each wrapped invocation tags the connector's span with
+	* `files.auth_mode = "on-behalf-of-user"` via AsyncLocalStorage
+	* propagation — no additional parent span is opened.
+	*/
+	_wrapVolumeAPIInUserContext(api, userCtx) {
+		const wrap = (operation, fn) => (...args) => this._withAuthModeAttributes(operation, "on-behalf-of-user", () => runInUserContext(userCtx, () => fn(...args)));
+		return {
+			list: wrap("list", api.list),
+			read: wrap("read", api.read),
+			download: wrap("download", api.download),
+			exists: wrap("exists", api.exists),
+			metadata: wrap("metadata", api.metadata),
+			upload: wrap("upload", api.upload),
+			createDirectory: wrap("createDirectory", api.createDirectory),
+			delete: wrap("delete", api.delete),
+			preview: wrap("preview", api.preview)
+		};
+	}
+	/**
+	* Creates a VolumeAPI for a specific volume key.
+	*
+	* Enforces the volume's policy before each operation.
+	*/
+	createVolumeAPI(volumeKey, user) {
 		const connector = this.volumeConnectors[volumeKey];
-		const noop = () => Promise.resolve();
-		const check = options?.bypassPolicy ? noop : (action, path, overrides) => this._checkPolicy(volumeKey, action, path, user, overrides);
+		const check = (action, path, overrides) => this._checkPolicy(volumeKey, action, path, user, overrides);
 		return {
 			list: async (directoryPath) => {
 				await check("list", directoryPath ?? "/");
@@ -845,15 +1262,22 @@ var FilesPlugin = class FilesPlugin extends Plugin {
 	* Returns the programmatic API for the Files plugin.
 	* Callable with a volume key to get a volume-scoped handle.
 	*
-	* All operations execute as the service principal.
-	* Use policies to control per-user access.
+	* SP volumes (`auth: "service-principal"`, the default) execute as the
+	* service principal. OBO volumes (`auth: "on-behalf-of-user"`) executed
+	* through the HTTP routes run as the end user; for programmatic calls
+	* outside a route, use `asUser(req)` to opt into per-user execution.
+	* `asUser(req)` is a hard override at the SDK level: it forces every
+	* subsequent call to execute as the end user inside `runInUserContext`,
+	* regardless of the volume's `auth` setting. Policies control per-user
+	* access in either mode.
 	*
 	* @example
 	* ```ts
 	* // Service principal access
 	* appKit.files("uploads").list()
 	*
-	* // With policy: pass user identity for access control
+	* // With policy: pass user identity for access control. The SDK call
+	* // also executes as the user (not the service principal).
 	* appKit.files("uploads").asUser(req).list()
 	* ```
 	*/
@@ -861,15 +1285,18 @@ var FilesPlugin = class FilesPlugin extends Plugin {
 		const resolveVolume = (volumeKey) => {
 			if (!this.volumeKeys.includes(volumeKey)) throw new Error(`Unknown volume "${volumeKey}". Available volumes: ${this.volumeKeys.join(", ")}`);
 			return {
-				...this.createVolumeAPI(volumeKey, {
+				...this._wrapVolumeAPIWithSPSpan(this.createVolumeAPI(volumeKey, {
 					get id() {
 						return getCurrentUserId();
 					},
 					isServicePrincipal: true
-				}),
+				})),
 				asUser: (req) => {
 					const user = this._extractUser(req);
-					return this.createVolumeAPI(volumeKey, user);
+					const api = this.createVolumeAPI(volumeKey, user);
+					const userCtx = this._buildUserContextOrNull(req);
+					if (!userCtx) return this._wrapVolumeAPIWithSPSpan(api);
+					return this._wrapVolumeAPIInUserContext(api, userCtx);
 				}
 			};
 		};