@databricks/appkit 0.82.0 → 0.84.0

package/dist/plugins/files/plugin.js

@@ -1,10 +1,10 @@
 import { ApiError } from "../../shared/src/workspace-client/errors.js";
 import { AuthenticationError } from "../../errors/authentication.js";
 import "../../errors/index.js";
-import { ServiceContext } from "../../context/service-context.js";
+import { isCallerContext } from "../../context/caller-context.js";
 import { createLogger } from "../../logging/logger.js";
-import { isUserContext } from "../../context/user-context.js";
-import { getCurrentUserId, getExecutionContext, getWorkspaceClient, runInUserContext } from "../../context/execution-context.js";
+import { ServiceContext } from "../../context/service-context.js";
+import { getCallerContext, getCurrentPrincipalId, getExecutionContext, getWorkspaceClient, runInCallerContext } from "../../context/execution-context.js";
 import "../../context/index.js";
 import { Plugin } from "../../plugin/plugin.js";
 import { toPlugin } from "../../plugin/to-plugin.js";
@@ -22,8 +22,8 @@ import { FILES_DOWNLOAD_DEFAULTS, FILES_MAX_UPLOAD_SIZE, FILES_READ_DEFAULTS, FI
 import { parentDirectory, sanitizeFilename } from "./helpers.js";
 import manifest_default from "./manifest.js";
 import { z } from "zod";
-import { STATUS_CODES } from "node:http";
 import { Readable } from "node:stream";
+import { STATUS_CODES } from "node:http";
 
 //#region src/plugins/files/plugin.ts
 const logger = createLogger("files");
@@ -113,7 +113,7 @@ var FilesPlugin = class FilesPlugin extends Plugin {
 	* 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),
+	* path also falls through to the SP client (no `runInCallerContext` wrap),
 	* so the policy user and the SDK identity stay aligned.
 	*/
 	_extractUser(req) {
@@ -126,7 +126,7 @@ var FilesPlugin = class FilesPlugin extends Plugin {
 		if (process.env.NODE_ENV === "development") {
 			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(),
+				id: getCurrentPrincipalId(),
 				isServicePrincipal: true
 			};
 		}
@@ -153,7 +153,7 @@ var FilesPlugin = class FilesPlugin extends Plugin {
 		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(),
+				id: getCurrentPrincipalId(),
 				isServicePrincipal: true
 			};
 		}
@@ -191,7 +191,7 @@ var FilesPlugin = class FilesPlugin extends Plugin {
 	* 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
+	* `runInCallerContext` 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`.
 	*/
@@ -205,7 +205,7 @@ var FilesPlugin = class FilesPlugin extends Plugin {
 				else {
 					logger.debug("No x-forwarded-user header — proceeding with service principal identity for policy evaluation.");
 					user = {
-						id: getCurrentUserId(),
+						id: getCurrentPrincipalId(),
 						isServicePrincipal: true
 					};
 				}
@@ -481,7 +481,7 @@ var FilesPlugin = class FilesPlugin extends Plugin {
 	*
 	* 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
+	* cache layer is keyed by `getCurrentPrincipalId()`, 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
@@ -501,7 +501,7 @@ var FilesPlugin = class FilesPlugin extends Plugin {
 	async _invalidateListCache(volumeKey, writtenPath, connector, mode = "service-principal") {
 		if (mode === "on-behalf-of-user") return;
 		const parent = parentDirectory(writtenPath);
-		const userKey = getCurrentUserId();
+		const userKey = getCurrentPrincipalId();
 		const tryDelete = async (segment) => {
 			try {
 				await this.cache.delete(this.cache.generateKey([`files:${volumeKey}:list`, segment], userKey));
@@ -942,7 +942,7 @@ var FilesPlugin = class FilesPlugin extends Plugin {
 		return this.volumeConfigs[volumeKey]?.auth ?? this.config.auth ?? "service-principal";
 	}
 	/**
-	* Build a `UserContext` from request headers when both
+	* Build a `CallerContext` 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
@@ -954,12 +954,12 @@ var FilesPlugin = class FilesPlugin extends Plugin {
 		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);
+		return ServiceContext.createCallerContext(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:
+	* whether `runInCallerContext` 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).
@@ -973,12 +973,12 @@ var FilesPlugin = class FilesPlugin extends Plugin {
 	}
 	/**
 	* One-shot resolver for HTTP route handlers. Builds the request's
-	* `UserContext` AT MOST ONCE (when the volume is OBO and the headers are
+	* `CallerContext` 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`.
+	* pre-built `CallerContext`.
 	*
 	* Handlers thread the `userCtx` into `_runWithAuth(userCtx, fn)` to avoid
-	* a second `ServiceContext.createUserContext()` allocation — that call
+	* a second `ServiceContext.createCallerContext()` allocation. That call
 	* builds a fresh `WorkspaceClient` per invocation, so doing it twice per
 	* request was pure throwaway overhead.
 	*/
@@ -999,11 +999,11 @@ var FilesPlugin = class FilesPlugin extends Plugin {
 	/**
 	* Run `fn` under the correct execution context.
 	* - `userCtx` is `null`: invokes `fn` directly so the service-principal
-	*   `WorkspaceClient` and `getCurrentUserId()` are used — identical
+	*   `WorkspaceClient` and `getCurrentPrincipalId()` 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
+	* - `userCtx` is a `CallerContext`: wraps `fn` in `runInCallerContext(userCtx)`,
+	*   so SDK calls execute as the end user and `getCurrentPrincipalId()` (and
 	*   therefore cache keys) resolve to the user's ID.
 	*
 	* The caller is responsible for building `userCtx` exactly once per
@@ -1011,7 +1011,7 @@ var FilesPlugin = class FilesPlugin extends Plugin {
 	* NOT take a `req` so it cannot accidentally re-build the context.
 	*/
 	async _runWithAuth(userCtx, fn) {
-		if (userCtx) return runInUserContext(userCtx, fn);
+		if (userCtx) return runInCallerContext(userCtx, fn);
 		return fn();
 	}
 	/**
@@ -1042,6 +1042,25 @@ var FilesPlugin = class FilesPlugin extends Plugin {
 	* additional parent span is opened, so each call produces exactly one
 	* `files.<operation>` span instead of two.
 	*/
+	/**
+	* Like `_wrapVolumeAPIWithSPSpan`, but picks `files.auth_mode` from the
+	* active scope at call time: "on-behalf-of-user" inside a caller scope
+	* (for example `appkit.asUser(req)`), "service-principal" otherwise.
+	*/
+	_wrapVolumeAPIWithScopeSpan(api) {
+		const wrap = (operation, fn) => (...args) => this._withAuthModeAttributes(operation, getCallerContext() ? "on-behalf-of-user" : "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)
+		};
+	}
 	_wrapVolumeAPIWithSPSpan(api) {
 		const wrap = (operation, fn) => (...args) => this._withAuthModeAttributes(operation, "service-principal", () => fn(...args));
 		return {
@@ -1058,10 +1077,10 @@ var FilesPlugin = class FilesPlugin extends Plugin {
 	}
 	/**
 	* Wrap each `VolumeAPI` method so its execution runs inside
-	* `runInUserContext(userCtx, ...)`. Used by `VolumeHandle.asUser(req)` to
+	* `runInCallerContext(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()`
+	* `createVolumeAPI`) runs inside the same scope, so `getCurrentPrincipalId()`
 	* and any cache `userKey` derived from it also resolve to the user.
 	*
 	* Each wrapped invocation tags the connector's span with
@@ -1069,7 +1088,7 @@ var FilesPlugin = class FilesPlugin extends Plugin {
 	* 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)));
+		const wrap = (operation, fn) => (...args) => this._withAuthModeAttributes(operation, "on-behalf-of-user", () => runInCallerContext(userCtx, () => fn(...args)));
 		return {
 			list: wrap("list", api.list),
 			read: wrap("read", api.read),
@@ -1142,7 +1161,7 @@ var FilesPlugin = class FilesPlugin extends Plugin {
 	_defineVolumeTools(volumeKey) {
 		const buildUser = () => {
 			const ctx = getExecutionContext();
-			return isUserContext(ctx) ? { id: ctx.userId } : {
+			return isCallerContext(ctx) ? { id: ctx.principal.userId } : {
 				id: ctx.serviceUserId,
 				isServicePrincipal: true
 			};
@@ -1265,7 +1284,7 @@ var FilesPlugin = class FilesPlugin extends Plugin {
 	* 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`,
+	* subsequent call to execute as the end user inside `runInCallerContext`,
 	* regardless of the volume's `auth` setting. Policies control per-user
 	* access in either mode.
 	*
@@ -1283,11 +1302,13 @@ 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._wrapVolumeAPIWithSPSpan(this.createVolumeAPI(volumeKey, {
+				...this._wrapVolumeAPIWithScopeSpan(this.createVolumeAPI(volumeKey, {
 					get id() {
-						return getCurrentUserId();
+						return getCurrentPrincipalId();
 					},
-					isServicePrincipal: true
+					get isServicePrincipal() {
+						return getCallerContext() === void 0;
+					}
 				})),
 				asUser: (req) => {
 					const user = this._extractUser(req);