@databricks/appkit 0.24.0 → 0.25.0

package/dist/plugins/files/plugin.js

@@ -1,7 +1,7 @@
 import { createLogger } from "../../logging/logger.js";
 import { AuthenticationError } from "../../errors/authentication.js";
 import { init_errors } from "../../errors/index.js";
-import { getWorkspaceClient, isInUserContext } from "../../context/execution-context.js";
+import { getCurrentUserId, getWorkspaceClient } from "../../context/execution-context.js";
 import { init_context } from "../../context/index.js";
 import { ResourceType } from "../../registry/types.generated.js";
 import "../../registry/index.js";
@@ -14,6 +14,7 @@ import "../../connectors/files/index.js";
 import { FILES_DOWNLOAD_DEFAULTS, FILES_MAX_UPLOAD_SIZE, FILES_READ_DEFAULTS, FILES_WRITE_DEFAULTS } from "./defaults.js";
 import { parentDirectory, sanitizeFilename } from "./helpers.js";
 import manifest_default from "./manifest.js";
+import { PolicyDeniedError, policy } from "./policy.js";
 import { ApiError } from "@databricks/sdk-experimental";
 import { STATUS_CODES } from "node:http";
 import { Readable } from "node:stream";
@@ -72,18 +73,72 @@ var FilesPlugin = class FilesPlugin extends Plugin {
 		}));
 	}
 	/**
-	* Warns when a method is called without a user context (i.e. as service principal).
-	* OBO access via `asUser(req)` is strongly recommended.
+	* Extract user identity from the request.
+	* Falls back to `getCurrentUserId()` in development mode.
 	*/
-	warnIfNoUserContext(volumeKey, method) {
-		if (!isInUserContext()) logger.warn(`app.files("${volumeKey}").${method}() called without user context (service principal). Please use OBO instead: app.files("${volumeKey}").asUser(req).${method}()`);
+	_extractUser(req) {
+		const userId = req.header("x-forwarded-user")?.trim();
+		if (userId) return { id: userId };
+		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() };
+		}
+		throw AuthenticationError.missingToken("Missing x-forwarded-user header. Cannot resolve user ID.");
+	}
+	/**
+	* Check the policy for a volume. No-op if no policy is configured.
+	* Throws `PolicyDeniedError` if denied.
+	*/
+	async _checkPolicy(volumeKey, action, path, user, resourceOverrides) {
+		const policyFn = this.volumeConfigs[volumeKey]?.policy;
+		if (typeof policyFn !== "function") return;
+		if (!await policyFn(action, {
+			path,
+			volume: volumeKey,
+			...resourceOverrides
+		}, user)) {
+			const userId = user.isServicePrincipal ? "<service-principal>" : user.id;
+			logger.warn("Policy denied \"%s\" on volume \"%s\" for user \"%s\"", action, volumeKey, userId);
+			throw new PolicyDeniedError(action, volumeKey);
+		}
 	}
 	/**
-	* Throws when a method is called without a user context (i.e. as service principal).
-	* OBO access via `asUser(req)` is enforced for now.
+	* HTTP-level wrapper around `_checkPolicy`.
+	* Extracts user (401 on failure), runs policy (403 on denial).
+	* Returns `true` if the request may proceed, `false` if a response was sent.
 	*/
-	throwIfNoUserContext(volumeKey, method) {
-		if (!isInUserContext()) throw new Error(`app.files("${volumeKey}").${method}() called without user context (service principal). Use OBO instead: app.files("${volumeKey}").asUser(req).${method}()`);
+	async _enforcePolicy(req, res, volumeKey, action, path, resourceOverrides) {
+		let user;
+		try {
+			user = this._extractUser(req);
+		} catch (error) {
+			if (error instanceof AuthenticationError) {
+				res.status(401).json({
+					error: error.message,
+					plugin: this.name
+				});
+				return false;
+			}
+			throw error;
+		}
+		try {
+			await this._checkPolicy(volumeKey, action, path, user, resourceOverrides);
+		} catch (error) {
+			if (error instanceof PolicyDeniedError) {
+				res.status(403).json({
+					error: error.message,
+					plugin: this.name
+				});
+				return false;
+			}
+			logger.error("Policy function threw on volume %s: %O", volumeKey, error);
+			res.status(500).json({
+				error: "Policy evaluation failed",
+				plugin: this.name
+			});
+			return false;
+		}
+		return true;
 	}
 	constructor(config) {
 		super(config);
@@ -97,7 +152,8 @@ var FilesPlugin = class FilesPlugin extends Plugin {
 			const volumePath = process.env[envVar];
 			const mergedConfig = {
 				maxUploadSize: volumeCfg.maxUploadSize ?? config.maxUploadSize,
-				customContentTypes: volumeCfg.customContentTypes ?? config.customContentTypes
+				customContentTypes: volumeCfg.customContentTypes ?? config.customContentTypes,
+				policy: volumeCfg.policy ?? policy.publicRead()
 			};
 			this.volumeConfigs[key] = mergedConfig;
 			this.volumeConnectors[key] = new FilesConnector({
@@ -107,51 +163,7 @@ var FilesPlugin = class FilesPlugin extends Plugin {
 				customContentTypes: mergedConfig.customContentTypes
 			});
 		}
-	}
-	/**
-	* Creates a VolumeAPI for a specific volume key.
-	* Each method warns if called outside a user context (service principal).
-	*/
-	createVolumeAPI(volumeKey) {
-		const connector = this.volumeConnectors[volumeKey];
-		return {
-			list: (directoryPath) => {
-				this.throwIfNoUserContext(volumeKey, `list`);
-				return connector.list(getWorkspaceClient(), directoryPath);
-			},
-			read: (filePath, options) => {
-				this.throwIfNoUserContext(volumeKey, `read`);
-				return connector.read(getWorkspaceClient(), filePath, options);
-			},
-			download: (filePath) => {
-				this.throwIfNoUserContext(volumeKey, `download`);
-				return connector.download(getWorkspaceClient(), filePath);
-			},
-			exists: (filePath) => {
-				this.throwIfNoUserContext(volumeKey, `exists`);
-				return connector.exists(getWorkspaceClient(), filePath);
-			},
-			metadata: (filePath) => {
-				this.throwIfNoUserContext(volumeKey, `metadata`);
-				return connector.metadata(getWorkspaceClient(), filePath);
-			},
-			upload: (filePath, contents, options) => {
-				this.throwIfNoUserContext(volumeKey, `upload`);
-				return connector.upload(getWorkspaceClient(), filePath, contents, options);
-			},
-			createDirectory: (directoryPath) => {
-				this.throwIfNoUserContext(volumeKey, `createDirectory`);
-				return connector.createDirectory(getWorkspaceClient(), directoryPath);
-			},
-			delete: (filePath) => {
-				this.throwIfNoUserContext(volumeKey, `delete`);
-				return connector.delete(getWorkspaceClient(), filePath);
-			},
-			preview: (filePath) => {
-				this.throwIfNoUserContext(volumeKey, `preview`);
-				return connector.preview(getWorkspaceClient(), filePath);
-			}
-		};
+		for (const key of this.volumeKeys) if (!volumes[key].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);
 	}
 	injectRoutes(router) {
 		this.route(router, {
@@ -310,14 +322,25 @@ var FilesPlugin = class FilesPlugin extends Plugin {
 	* 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.
+	*
+	* 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.
 	*/
-	_invalidateListCache(volumeKey, parentPath, userId, connector) {
+	_invalidateListCache(volumeKey, parentPath, connector) {
 		const parent = parentDirectory(parentPath);
 		const cachePathSegment = parent ? connector.resolvePath(parent) : "__root__";
-		const listKey = this.cache.generateKey([`files:${volumeKey}:list`, cachePathSegment], userId);
+		const listKey = this.cache.generateKey([`files:${volumeKey}:list`, cachePathSegment], getCurrentUserId());
 		this.cache.delete(listKey);
 	}
 	_handleApiError(res, error, fallbackMessage) {
+		if (error instanceof PolicyDeniedError) {
+			res.status(403).json({
+				error: error.message,
+				plugin: this.name
+			});
+			return;
+		}
 		if (error instanceof AuthenticationError) {
 			res.status(401).json({
 				error: error.message,
@@ -356,11 +379,9 @@ var FilesPlugin = class FilesPlugin extends Plugin {
 	}
 	async _handleList(req, res, connector, volumeKey) {
 		const path = req.query.path;
+		if (!await this._enforcePolicy(req, res, volumeKey, "list", path ?? "/")) return;
 		try {
-			const result = await this.asUser(req).execute(async () => {
-				this.warnIfNoUserContext(volumeKey, `list`);
-				return connector.list(getWorkspaceClient(), path);
-			}, this._readSettings([`files:${volumeKey}:list`, path ? connector.resolvePath(path) : "__root__"]));
+			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;
@@ -380,11 +401,9 @@ var FilesPlugin = class FilesPlugin extends Plugin {
 			});
 			return;
 		}
+		if (!await this._enforcePolicy(req, res, volumeKey, "read", path)) return;
 		try {
-			const result = await this.asUser(req).execute(async () => {
-				this.warnIfNoUserContext(volumeKey, `read`);
-				return connector.read(getWorkspaceClient(), path);
-			}, this._readSettings([`files:${volumeKey}:read`, connector.resolvePath(path)]));
+			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;
@@ -415,15 +434,12 @@ var FilesPlugin = class FilesPlugin extends Plugin {
 			});
 			return;
 		}
+		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 userPlugin = this.asUser(req);
 			const settings = { default: FILES_DOWNLOAD_DEFAULTS };
-			const response = await userPlugin.execute(async () => {
-				this.warnIfNoUserContext(volumeKey, `download`);
-				return connector.download(getWorkspaceClient(), path);
-			}, settings);
+			const response = await this.execute(async () => connector.download(getWorkspaceClient(), path), settings);
 			if (!response.ok) {
 				this._sendStatusError(res, response.status);
 				return;
@@ -459,11 +475,9 @@ var FilesPlugin = class FilesPlugin extends Plugin {
 			});
 			return;
 		}
+		if (!await this._enforcePolicy(req, res, volumeKey, "exists", path)) return;
 		try {
-			const result = await this.asUser(req).execute(async () => {
-				this.warnIfNoUserContext(volumeKey, `exists`);
-				return connector.exists(getWorkspaceClient(), path);
-			}, this._readSettings([`files:${volumeKey}:exists`, connector.resolvePath(path)]));
+			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;
@@ -483,11 +497,9 @@ var FilesPlugin = class FilesPlugin extends Plugin {
 			});
 			return;
 		}
+		if (!await this._enforcePolicy(req, res, volumeKey, "metadata", path)) return;
 		try {
-			const result = await this.asUser(req).execute(async () => {
-				this.warnIfNoUserContext(volumeKey, `metadata`);
-				return connector.metadata(getWorkspaceClient(), path);
-			}, this._readSettings([`files:${volumeKey}:metadata`, connector.resolvePath(path)]));
+			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;
@@ -507,11 +519,9 @@ var FilesPlugin = class FilesPlugin extends Plugin {
 			});
 			return;
 		}
+		if (!await this._enforcePolicy(req, res, volumeKey, "preview", path)) return;
 		try {
-			const result = await this.asUser(req).execute(async () => {
-				this.warnIfNoUserContext(volumeKey, `preview`);
-				return connector.preview(getWorkspaceClient(), path);
-			}, this._readSettings([`files:${volumeKey}:preview`, connector.resolvePath(path)]));
+			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;
@@ -533,8 +543,19 @@ var FilesPlugin = class FilesPlugin extends Plugin {
 		}
 		const maxSize = this.volumeConfigs[volumeKey].maxUploadSize ?? FILES_MAX_UPLOAD_SIZE;
 		const rawContentLength = req.headers["content-length"];
-		const contentLength = rawContentLength ? parseInt(rawContentLength, 10) : void 0;
-		if (contentLength !== void 0 && !Number.isNaN(contentLength) && contentLength > maxSize) {
+		let contentLength;
+		if (typeof rawContentLength === "string" && rawContentLength.length > 0) {
+			if (!/^\d+$/.test(rawContentLength)) {
+				res.status(400).json({
+					error: "Invalid Content-Length header.",
+					plugin: this.name
+				});
+				return;
+			}
+			contentLength = Number(rawContentLength);
+		}
+		if (!await this._enforcePolicy(req, res, volumeKey, "upload", path, { size: contentLength })) return;
+		if (contentLength !== void 0 && contentLength > maxSize) {
 			res.status(413).json({
 				error: `File size (${contentLength} bytes) exceeds maximum allowed size (${maxSize} bytes).`,
 				plugin: this.name
@@ -554,14 +575,12 @@ var FilesPlugin = class FilesPlugin extends Plugin {
 				controller.enqueue(chunk);
 			} }));
 			logger.debug(req, "Upload body received: volume=%s path=%s, size=%d bytes", volumeKey, path, contentLength ?? 0);
-			const userPlugin = this.asUser(req);
 			const settings = { default: FILES_WRITE_DEFAULTS };
-			const result = await this.trackWrite(() => userPlugin.execute(async () => {
-				this.warnIfNoUserContext(volumeKey, `upload`);
+			const result = await this.trackWrite(() => this.execute(async () => {
 				await connector.upload(getWorkspaceClient(), path, webStream);
 				return { success: true };
 			}, settings));
-			this._invalidateListCache(volumeKey, path, this.resolveUserId(req), connector);
+			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);
@@ -590,15 +609,14 @@ var FilesPlugin = class FilesPlugin extends Plugin {
 			});
 			return;
 		}
+		if (!await this._enforcePolicy(req, res, volumeKey, "mkdir", dirPath)) return;
 		try {
-			const userPlugin = this.asUser(req);
 			const settings = { default: FILES_WRITE_DEFAULTS };
-			const result = await this.trackWrite(() => userPlugin.execute(async () => {
-				this.warnIfNoUserContext(volumeKey, `createDirectory`);
+			const result = await this.trackWrite(() => this.execute(async () => {
 				await connector.createDirectory(getWorkspaceClient(), dirPath);
 				return { success: true };
 			}, settings));
-			this._invalidateListCache(volumeKey, dirPath, this.resolveUserId(req), connector);
+			this._invalidateListCache(volumeKey, dirPath, connector);
 			if (!result.ok) {
 				this._sendStatusError(res, result.status);
 				return;
@@ -619,15 +637,14 @@ var FilesPlugin = class FilesPlugin extends Plugin {
 			return;
 		}
 		const path = rawPath;
+		if (!await this._enforcePolicy(req, res, volumeKey, "delete", path)) return;
 		try {
-			const userPlugin = this.asUser(req);
 			const settings = { default: FILES_WRITE_DEFAULTS };
-			const result = await this.trackWrite(() => userPlugin.execute(async () => {
-				this.warnIfNoUserContext(volumeKey, `delete`);
+			const result = await this.trackWrite(() => this.execute(async () => {
 				await connector.delete(getWorkspaceClient(), path);
 				return { success: true };
 			}, settings));
-			this._invalidateListCache(volumeKey, path, this.resolveUserId(req), connector);
+			this._invalidateListCache(volumeKey, path, connector);
 			if (!result.ok) {
 				this._sendStatusError(res, result.status);
 				return;
@@ -637,6 +654,59 @@ var FilesPlugin = class FilesPlugin extends Plugin {
 			this._handleApiError(res, error, "Delete failed");
 		}
 	}
+	/**
+	* Creates a VolumeAPI for a specific volume key.
+	*
+	* 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.
+	*
+	* @security When `bypassPolicy` is `true`, no policy enforcement runs.
+	* Do not expose bypassed APIs to HTTP routes or end-user code paths.
+	*/
+	createVolumeAPI(volumeKey, user, options) {
+		const connector = this.volumeConnectors[volumeKey];
+		const noop = () => Promise.resolve();
+		const check = options?.bypassPolicy ? noop : (action, path, overrides) => this._checkPolicy(volumeKey, action, path, user, overrides);
+		return {
+			list: async (directoryPath) => {
+				await check("list", directoryPath ?? "/");
+				return connector.list(getWorkspaceClient(), directoryPath);
+			},
+			read: async (filePath, opts) => {
+				await check("read", filePath);
+				return connector.read(getWorkspaceClient(), filePath, opts);
+			},
+			download: async (filePath) => {
+				await check("download", filePath);
+				return connector.download(getWorkspaceClient(), filePath);
+			},
+			exists: async (filePath) => {
+				await check("exists", filePath);
+				return connector.exists(getWorkspaceClient(), filePath);
+			},
+			metadata: async (filePath) => {
+				await check("metadata", filePath);
+				return connector.metadata(getWorkspaceClient(), filePath);
+			},
+			upload: async (filePath, contents, opts) => {
+				await check("upload", filePath);
+				return connector.upload(getWorkspaceClient(), filePath, contents, opts);
+			},
+			createDirectory: async (directoryPath) => {
+				await check("mkdir", directoryPath);
+				return connector.createDirectory(getWorkspaceClient(), directoryPath);
+			},
+			delete: async (filePath) => {
+				await check("delete", filePath);
+				return connector.delete(getWorkspaceClient(), filePath);
+			},
+			preview: async (filePath) => {
+				await check("preview", filePath);
+				return connector.preview(getWorkspaceClient(), filePath);
+			}
+		};
+	}
 	inflightWrites = 0;
 	trackWrite(fn) {
 		this.inflightWrites++;
@@ -657,22 +727,31 @@ 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.
+	*
 	* @example
 	* ```ts
-	* // OBO access (recommended)
-	* appKit.files("uploads").asUser(req).list()
-	*
-	* // Service principal access (logs a warning)
+	* // Service principal access
 	* appKit.files("uploads").list()
+	*
+	* // With policy: pass user identity for access control
+	* appKit.files("uploads").asUser(req).list()
 	* ```
 	*/
 	exports() {
 		const resolveVolume = (volumeKey) => {
 			if (!this.volumeKeys.includes(volumeKey)) throw new Error(`Unknown volume "${volumeKey}". Available volumes: ${this.volumeKeys.join(", ")}`);
 			return {
-				...this.createVolumeAPI(volumeKey),
+				...this.createVolumeAPI(volumeKey, {
+					get id() {
+						return getCurrentUserId();
+					},
+					isServicePrincipal: true
+				}),
 				asUser: (req) => {
-					return this.asUser(req).createVolumeAPI(volumeKey);
+					const user = this._extractUser(req);
+					return this.createVolumeAPI(volumeKey, user);
 				}
 			};
 		};
@@ -687,7 +766,7 @@ var FilesPlugin = class FilesPlugin extends Plugin {
 /**
 * @internal
 */
-const files$1 = toPlugin(FilesPlugin);
+const files$1 = Object.assign(toPlugin(FilesPlugin), { policy });
 
 //#endregion
 export { FilesPlugin, files$1 as files };