@databricks/appkit 0.35.1 → 0.35.2

package/dist/plugins/files/plugin.js.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.js","names":["manifest","files"],"sources":["../../../src/plugins/files/plugin.ts"],"sourcesContent":["import { STATUS_CODES } from \"node:http\";\nimport { Readable } from \"node:stream\";\nimport { ApiError } from \"@databricks/sdk-experimental\";\nimport type express from \"express\";\nimport type {\n  AgentToolDefinition,\n  IAppRouter,\n  PluginExecutionSettings,\n  ToolProvider,\n} from \"shared\";\nimport { z } from \"zod\";\nimport {\n  contentTypeFromPath,\n  FilesConnector,\n  isSafeInlineContentType,\n  validateCustomContentTypes,\n} from \"../../connectors/files\";\nimport {\n  getCurrentUserId,\n  getExecutionContext,\n  getWorkspaceClient,\n} from \"../../context\";\nimport { isUserContext } from \"../../context/user-context\";\nimport { buildToolkitEntries } from \"../../core/agent/build-toolkit\";\nimport {\n  defineTool,\n  executeFromRegistry,\n  type ToolRegistry,\n  toolsFromRegistry,\n} from \"../../core/agent/tools/define-tool\";\nimport { AuthenticationError } from \"../../errors\";\nimport { createLogger } from \"../../logging/logger\";\nimport { Plugin, toPlugin } from \"../../plugin\";\nimport type { PluginManifest, ResourceRequirement } from \"../../registry\";\nimport { ResourceType } from \"../../registry\";\nimport {\n  FILES_DOWNLOAD_DEFAULTS,\n  FILES_MAX_UPLOAD_SIZE,\n  FILES_READ_DEFAULTS,\n  FILES_WRITE_DEFAULTS,\n} from \"./defaults\";\nimport { parentDirectory, sanitizeFilename } from \"./helpers\";\nimport manifest from \"./manifest.json\";\nimport {\n  type FileAction,\n  type FilePolicyUser,\n  type FileResource,\n  PolicyDeniedError,\n  policy,\n} from \"./policy\";\nimport type {\n  FilesExport,\n  IFilesConfig,\n  VolumeAPI,\n  VolumeConfig,\n  VolumeHandle,\n} from \"./types\";\n\nconst logger = createLogger(\"files\");\n\nexport class FilesPlugin extends Plugin implements ToolProvider {\n  name = \"files\";\n\n  /** Plugin manifest declaring metadata and resource requirements. */\n  static manifest = manifest as PluginManifest;\n  protected static description = \"Files plugin for Databricks file operations\";\n  protected declare config: IFilesConfig;\n\n  private volumeConnectors: Record<string, FilesConnector> = {};\n  private volumeConfigs: Record<string, VolumeConfig> = {};\n  private volumeKeys: string[] = [];\n  private tools: ToolRegistry = {};\n\n  /**\n   * Scans `process.env` for `DATABRICKS_VOLUME_*` keys and merges them with\n   * any explicitly configured volumes. Explicit config wins for per-volume\n   * overrides; auto-discovered volumes get default `{}` config.\n   */\n  static discoverVolumes(config: IFilesConfig): Record<string, VolumeConfig> {\n    const explicit = config.volumes ?? {};\n    const discovered: Record<string, VolumeConfig> = {};\n\n    const prefix = \"DATABRICKS_VOLUME_\";\n    for (const key of Object.keys(process.env)) {\n      if (!key.startsWith(prefix)) continue;\n      const suffix = key.slice(prefix.length);\n      if (!suffix) continue;\n      if (!process.env[key]) continue;\n      const volumeKey = suffix.toLowerCase();\n      if (!(volumeKey in explicit)) {\n        discovered[volumeKey] = {};\n      }\n    }\n\n    return { ...discovered, ...explicit };\n  }\n\n  /**\n   * Generates resource requirements dynamically from discovered + configured volumes.\n   * Each volume key maps to a `DATABRICKS_VOLUME_{KEY_UPPERCASE}` env var.\n   */\n  static getResourceRequirements(config: IFilesConfig): ResourceRequirement[] {\n    const volumes = FilesPlugin.discoverVolumes(config);\n    return Object.keys(volumes).map((key) => ({\n      type: ResourceType.VOLUME,\n      alias: `volume-${key}`,\n      resourceKey: `volume-${key}`,\n      description: `Unity Catalog Volume for \"${key}\" file storage`,\n      permission: \"WRITE_VOLUME\",\n      fields: {\n        path: {\n          env: `DATABRICKS_VOLUME_${key.toUpperCase()}`,\n          description: `Volume path for \"${key}\" (e.g. /Volumes/catalog/schema/volume_name)`,\n        },\n      },\n      required: true,\n    }));\n  }\n\n  /**\n   * Extract user identity from the request.\n   * Falls back to `getCurrentUserId()` in development mode.\n   */\n  private _extractUser(req: express.Request): FilePolicyUser {\n    const userId = req.header(\"x-forwarded-user\")?.trim();\n    if (userId) return { id: userId };\n    if (process.env.NODE_ENV === \"development\") {\n      logger.warn(\n        \"No x-forwarded-user header — falling back to service principal identity for policy checks. \" +\n          \"Ensure your proxy forwards user headers to test per-user policies.\",\n      );\n      return { id: getCurrentUserId() };\n    }\n    throw AuthenticationError.missingToken(\n      \"Missing x-forwarded-user header. Cannot resolve user ID.\",\n    );\n  }\n\n  /**\n   * Check the policy for a volume. No-op if no policy is configured.\n   * Throws `PolicyDeniedError` if denied.\n   */\n  private async _checkPolicy(\n    volumeKey: string,\n    action: FileAction,\n    path: string,\n    user: FilePolicyUser,\n    resourceOverrides?: Partial<FileResource>,\n  ): Promise<void> {\n    const policyFn = this.volumeConfigs[volumeKey]?.policy;\n    if (typeof policyFn !== \"function\") return;\n\n    const resource: FileResource = {\n      path,\n      volume: volumeKey,\n      ...resourceOverrides,\n    };\n    const allowed = await policyFn(action, resource, user);\n    if (!allowed) {\n      const userId = user.isServicePrincipal ? \"<service-principal>\" : user.id;\n      logger.warn(\n        'Policy denied \"%s\" on volume \"%s\" for user \"%s\"',\n        action,\n        volumeKey,\n        userId,\n      );\n      throw new PolicyDeniedError(action, volumeKey);\n    }\n  }\n\n  /**\n   * HTTP-level wrapper around `_checkPolicy`.\n   * Extracts user (401 on failure), runs policy (403 on denial).\n   * Returns `true` if the request may proceed, `false` if a response was sent.\n   */\n  private async _enforcePolicy(\n    req: express.Request,\n    res: express.Response,\n    volumeKey: string,\n    action: FileAction,\n    path: string,\n    resourceOverrides?: Partial<FileResource>,\n  ): Promise<boolean> {\n    let user: FilePolicyUser;\n    try {\n      user = this._extractUser(req);\n    } catch (error) {\n      if (error instanceof AuthenticationError) {\n        res.status(401).json({ error: error.message, plugin: this.name });\n        return false;\n      }\n      throw error;\n    }\n\n    try {\n      await this._checkPolicy(volumeKey, action, path, user, resourceOverrides);\n    } catch (error) {\n      if (error instanceof PolicyDeniedError) {\n        res.status(403).json({ error: error.message, plugin: this.name });\n        return false;\n      }\n      // A crashing policy is treated as a server error (fail closed).\n      logger.error(\"Policy function threw on volume %s: %O\", volumeKey, error);\n      res.status(500).json({\n        error: \"Policy evaluation failed\",\n        plugin: this.name,\n      });\n      return false;\n    }\n\n    return true;\n  }\n\n  constructor(config: IFilesConfig) {\n    super(config);\n    this.config = config;\n\n    if (config.customContentTypes) {\n      validateCustomContentTypes(config.customContentTypes);\n    }\n\n    const volumes = FilesPlugin.discoverVolumes(config);\n    this.volumeKeys = Object.keys(volumes);\n\n    for (const key of this.volumeKeys) {\n      const volumeCfg = volumes[key];\n      const envVar = `DATABRICKS_VOLUME_${key.toUpperCase()}`;\n      const volumePath = process.env[envVar];\n\n      // Merge per-volume config with plugin-level defaults\n      const mergedConfig: VolumeConfig = {\n        maxUploadSize: volumeCfg.maxUploadSize ?? config.maxUploadSize,\n        customContentTypes:\n          volumeCfg.customContentTypes ?? config.customContentTypes,\n        policy: volumeCfg.policy ?? policy.publicRead(),\n      };\n      this.volumeConfigs[key] = mergedConfig;\n\n      this.volumeConnectors[key] = new FilesConnector({\n        defaultVolume: volumePath,\n        timeout: config.timeout,\n        telemetry: config.telemetry,\n        customContentTypes: mergedConfig.customContentTypes,\n      });\n\n      Object.assign(this.tools, this._defineVolumeTools(key));\n\n      // Warn at startup for volumes without an explicit policy\n      if (!volumeCfg.policy) {\n        logger.warn(\n          'Volume \"%s\" has no explicit policy — defaulting to publicRead(). ' +\n            \"Set a policy in files({ volumes: { %s: { policy: ... } } }) to silence this warning.\",\n          key,\n          key,\n        );\n      }\n    }\n  }\n\n  injectRoutes(router: IAppRouter) {\n    this.route(router, {\n      name: \"volumes\",\n      method: \"get\",\n      path: \"/volumes\",\n      handler: async (_req: express.Request, res: express.Response) => {\n        res.json({ volumes: this.volumeKeys });\n      },\n    });\n\n    this.route(router, {\n      name: \"list\",\n      method: \"get\",\n      path: \"/:volumeKey/list\",\n      handler: async (req: express.Request, res: express.Response) => {\n        const { connector, volumeKey } = this._resolveVolume(req, res);\n        if (!connector) return;\n        await this._handleList(req, res, connector, volumeKey);\n      },\n    });\n\n    this.route(router, {\n      name: \"read\",\n      method: \"get\",\n      path: \"/:volumeKey/read\",\n      handler: async (req: express.Request, res: express.Response) => {\n        const { connector, volumeKey } = this._resolveVolume(req, res);\n        if (!connector) return;\n        await this._handleRead(req, res, connector, volumeKey);\n      },\n    });\n\n    this.route(router, {\n      name: \"download\",\n      method: \"get\",\n      path: \"/:volumeKey/download\",\n      handler: async (req: express.Request, res: express.Response) => {\n        const { connector, volumeKey } = this._resolveVolume(req, res);\n        if (!connector) return;\n        await this._handleDownload(req, res, connector, volumeKey);\n      },\n    });\n\n    this.route(router, {\n      name: \"raw\",\n      method: \"get\",\n      path: \"/:volumeKey/raw\",\n      handler: async (req: express.Request, res: express.Response) => {\n        const { connector, volumeKey } = this._resolveVolume(req, res);\n        if (!connector) return;\n        await this._handleRaw(req, res, connector, volumeKey);\n      },\n    });\n\n    this.route(router, {\n      name: \"exists\",\n      method: \"get\",\n      path: \"/:volumeKey/exists\",\n      handler: async (req: express.Request, res: express.Response) => {\n        const { connector, volumeKey } = this._resolveVolume(req, res);\n        if (!connector) return;\n        await this._handleExists(req, res, connector, volumeKey);\n      },\n    });\n\n    this.route(router, {\n      name: \"metadata\",\n      method: \"get\",\n      path: \"/:volumeKey/metadata\",\n      handler: async (req: express.Request, res: express.Response) => {\n        const { connector, volumeKey } = this._resolveVolume(req, res);\n        if (!connector) return;\n        await this._handleMetadata(req, res, connector, volumeKey);\n      },\n    });\n\n    this.route(router, {\n      name: \"preview\",\n      method: \"get\",\n      path: \"/:volumeKey/preview\",\n      handler: async (req: express.Request, res: express.Response) => {\n        const { connector, volumeKey } = this._resolveVolume(req, res);\n        if (!connector) return;\n        await this._handlePreview(req, res, connector, volumeKey);\n      },\n    });\n\n    this.route(router, {\n      name: \"upload\",\n      method: \"post\",\n      path: \"/:volumeKey/upload\",\n      skipBodyParsing: true,\n      handler: async (req: express.Request, res: express.Response) => {\n        const { connector, volumeKey } = this._resolveVolume(req, res);\n        if (!connector) return;\n        await this._handleUpload(req, res, connector, volumeKey);\n      },\n    });\n\n    this.route(router, {\n      name: \"mkdir\",\n      method: \"post\",\n      path: \"/:volumeKey/mkdir\",\n      handler: async (req: express.Request, res: express.Response) => {\n        const { connector, volumeKey } = this._resolveVolume(req, res);\n        if (!connector) return;\n        await this._handleMkdir(req, res, connector, volumeKey);\n      },\n    });\n\n    this.route(router, {\n      name: \"delete\",\n      method: \"delete\",\n      path: \"/:volumeKey\",\n      handler: async (req: express.Request, res: express.Response) => {\n        const { connector, volumeKey } = this._resolveVolume(req, res);\n        if (!connector) return;\n        await this._handleDelete(req, res, connector, volumeKey);\n      },\n    });\n  }\n\n  /**\n   * Resolve `:volumeKey` from the request. Returns the connector and key,\n   * or sends a 404 and returns `{ connector: undefined }`.\n   */\n  private _resolveVolume(\n    req: express.Request,\n    res: express.Response,\n  ):\n    | { connector: FilesConnector; volumeKey: string }\n    | { connector: undefined; volumeKey: undefined } {\n    const volumeKey = req.params.volumeKey;\n    const connector = this.volumeConnectors[volumeKey];\n    if (!connector) {\n      const safeKey = volumeKey.replace(/[^a-zA-Z0-9_-]/g, \"\");\n      res.status(404).json({\n        error: `Unknown volume \"${safeKey}\"`,\n        plugin: this.name,\n      });\n      return { connector: undefined, volumeKey: undefined };\n    }\n    return { connector, volumeKey };\n  }\n\n  /**\n   * Validate a file/directory path from user input.\n   * Returns `true` if valid, or an error message string if invalid.\n   */\n  private _isValidPath(path: string | undefined): true | string {\n    if (!path) return \"path is required\";\n    if (path.length > 4096)\n      return `path exceeds maximum length of 4096 characters (got ${path.length})`;\n    if (path.includes(\"\\0\")) return \"path must not contain null bytes\";\n    return true;\n  }\n\n  private _readSettings(\n    cacheKey: (string | number | object)[],\n  ): PluginExecutionSettings {\n    return {\n      default: {\n        ...FILES_READ_DEFAULTS,\n        cache: { ...FILES_READ_DEFAULTS.cache, cacheKey },\n      },\n    };\n  }\n\n  /**\n   * Invalidate cached list entries for a directory after a write operation.\n   * Uses the same cache-key format as `_handleList`: resolved path for\n   * subdirectories, `\"__root__\"` for the volume root.\n   *\n   * Cache keys include `getCurrentUserId()` — must match the identity used\n   * by `this.execute()` in `_handleList`. Both run in service-principal\n   * context; wrapping either in `runInUserContext` would break invalidation.\n   */\n  private _invalidateListCache(\n    volumeKey: string,\n    parentPath: string,\n    connector: FilesConnector,\n  ): void {\n    const parent = parentDirectory(parentPath);\n    const cachePathSegment = parent\n      ? connector.resolvePath(parent)\n      : \"__root__\";\n    const listKey = this.cache.generateKey(\n      [`files:${volumeKey}:list`, cachePathSegment],\n      getCurrentUserId(),\n    );\n    this.cache.delete(listKey);\n  }\n\n  private _handleApiError(\n    res: express.Response,\n    error: unknown,\n    fallbackMessage: string,\n  ): void {\n    if (error instanceof PolicyDeniedError) {\n      res.status(403).json({\n        error: error.message,\n        plugin: this.name,\n      });\n      return;\n    }\n    if (error instanceof AuthenticationError) {\n      res.status(401).json({\n        error: error.message,\n        plugin: this.name,\n      });\n      return;\n    }\n    if (error instanceof ApiError) {\n      const status = error.statusCode ?? 500;\n      if (status >= 400 && status < 500) {\n        res.status(status).json({\n          error: error.message,\n          statusCode: status,\n          plugin: this.name,\n        });\n        return;\n      }\n      logger.error(\"Upstream server error in %s: %O\", this.name, error);\n      res.status(500).json({ error: fallbackMessage, plugin: this.name });\n      return;\n    }\n    logger.error(\"Unhandled error in %s: %O\", this.name, error);\n    res.status(500).json({ error: fallbackMessage, plugin: this.name });\n  }\n\n  private _sendStatusError(res: express.Response, status: number): void {\n    res.status(status).json({\n      error: STATUS_CODES[status] ?? \"Unknown Error\",\n      plugin: this.name,\n    });\n  }\n\n  private async _handleList(\n    req: express.Request,\n    res: express.Response,\n    connector: FilesConnector,\n    volumeKey: string,\n  ): Promise<void> {\n    const path = req.query.path as string | undefined;\n\n    if (!(await this._enforcePolicy(req, res, volumeKey, \"list\", path ?? \"/\")))\n      return;\n\n    try {\n      const result = await this.execute(\n        async () => connector.list(getWorkspaceClient(), path),\n        this._readSettings([\n          `files:${volumeKey}:list`,\n          path ? connector.resolvePath(path) : \"__root__\",\n        ]),\n      );\n\n      if (!result.ok) {\n        this._sendStatusError(res, result.status);\n        return;\n      }\n      res.json(result.data);\n    } catch (error) {\n      this._handleApiError(res, error, \"List failed\");\n    }\n  }\n\n  private async _handleRead(\n    req: express.Request,\n    res: express.Response,\n    connector: FilesConnector,\n    volumeKey: string,\n  ): Promise<void> {\n    const path = req.query.path as string;\n\n    const valid = this._isValidPath(path);\n    if (valid !== true) {\n      res.status(400).json({ error: valid, plugin: this.name });\n      return;\n    }\n\n    if (!(await this._enforcePolicy(req, res, volumeKey, \"read\", path))) return;\n\n    try {\n      const result = await this.execute(\n        async () => connector.read(getWorkspaceClient(), path),\n        this._readSettings([\n          `files:${volumeKey}:read`,\n          connector.resolvePath(path),\n        ]),\n      );\n\n      if (!result.ok) {\n        this._sendStatusError(res, result.status);\n        return;\n      }\n      res.type(\"text/plain\").send(result.data);\n    } catch (error) {\n      this._handleApiError(res, error, \"Read failed\");\n    }\n  }\n\n  private async _handleDownload(\n    req: express.Request,\n    res: express.Response,\n    connector: FilesConnector,\n    volumeKey: string,\n  ): Promise<void> {\n    return this._serveFile(req, res, connector, volumeKey, {\n      mode: \"download\",\n    });\n  }\n\n  private async _handleRaw(\n    req: express.Request,\n    res: express.Response,\n    connector: FilesConnector,\n    volumeKey: string,\n  ): Promise<void> {\n    return this._serveFile(req, res, connector, volumeKey, {\n      mode: \"raw\",\n    });\n  }\n\n  /**\n   * Shared handler for `/download` and `/raw` endpoints.\n   * - `download`: always forces `Content-Disposition: attachment`.\n   * - `raw`: adds CSP sandbox; forces attachment only for unsafe content types.\n   */\n  private async _serveFile(\n    req: express.Request,\n    res: express.Response,\n    connector: FilesConnector,\n    volumeKey: string,\n    opts: { mode: \"download\" | \"raw\" },\n  ): Promise<void> {\n    const path = req.query.path as string;\n\n    const valid = this._isValidPath(path);\n    if (valid !== true) {\n      res.status(400).json({ error: valid, plugin: this.name });\n      return;\n    }\n\n    if (!(await this._enforcePolicy(req, res, volumeKey, opts.mode, path)))\n      return;\n\n    const label = opts.mode === \"download\" ? \"Download\" : \"Raw fetch\";\n    const volumeCfg = this.volumeConfigs[volumeKey];\n\n    try {\n      const settings: PluginExecutionSettings = {\n        default: FILES_DOWNLOAD_DEFAULTS,\n      };\n      const response = await this.execute(\n        async () => connector.download(getWorkspaceClient(), path),\n        settings,\n      );\n\n      if (!response.ok) {\n        this._sendStatusError(res, response.status);\n        return;\n      }\n\n      const resolvedType = contentTypeFromPath(\n        path,\n        undefined,\n        volumeCfg.customContentTypes,\n      );\n      const fileName = sanitizeFilename(path.split(\"/\").pop() ?? \"download\");\n\n      res.setHeader(\"Content-Type\", resolvedType);\n      res.setHeader(\"X-Content-Type-Options\", \"nosniff\");\n\n      if (opts.mode === \"raw\") {\n        res.setHeader(\"Content-Security-Policy\", \"sandbox\");\n        if (!isSafeInlineContentType(resolvedType)) {\n          res.setHeader(\n            \"Content-Disposition\",\n            `attachment; filename=\"${fileName}\"`,\n          );\n        }\n      } else {\n        res.setHeader(\n          \"Content-Disposition\",\n          `attachment; filename=\"${fileName}\"`,\n        );\n      }\n\n      if (response.data.contents) {\n        const nodeStream = Readable.fromWeb(\n          response.data.contents as import(\"node:stream/web\").ReadableStream,\n        );\n        nodeStream.on(\"error\", (err) => {\n          logger.error(\"Stream error during %s: %O\", opts.mode, err);\n          if (!res.headersSent) {\n            this._sendStatusError(res, 500);\n          } else {\n            res.destroy();\n          }\n        });\n        nodeStream.pipe(res);\n      } else {\n        res.end();\n      }\n    } catch (error) {\n      this._handleApiError(res, error, `${label} failed`);\n    }\n  }\n\n  private async _handleExists(\n    req: express.Request,\n    res: express.Response,\n    connector: FilesConnector,\n    volumeKey: string,\n  ): Promise<void> {\n    const path = req.query.path as string;\n\n    const valid = this._isValidPath(path);\n    if (valid !== true) {\n      res.status(400).json({ error: valid, plugin: this.name });\n      return;\n    }\n\n    if (!(await this._enforcePolicy(req, res, volumeKey, \"exists\", path)))\n      return;\n\n    try {\n      const result = await this.execute(\n        async () => connector.exists(getWorkspaceClient(), path),\n        this._readSettings([\n          `files:${volumeKey}:exists`,\n          connector.resolvePath(path),\n        ]),\n      );\n\n      if (!result.ok) {\n        this._sendStatusError(res, result.status);\n        return;\n      }\n      res.json({ exists: result.data });\n    } catch (error) {\n      this._handleApiError(res, error, \"Exists check failed\");\n    }\n  }\n\n  private async _handleMetadata(\n    req: express.Request,\n    res: express.Response,\n    connector: FilesConnector,\n    volumeKey: string,\n  ): Promise<void> {\n    const path = req.query.path as string;\n\n    const valid = this._isValidPath(path);\n    if (valid !== true) {\n      res.status(400).json({ error: valid, plugin: this.name });\n      return;\n    }\n\n    if (!(await this._enforcePolicy(req, res, volumeKey, \"metadata\", path)))\n      return;\n\n    try {\n      const result = await this.execute(\n        async () => connector.metadata(getWorkspaceClient(), path),\n        this._readSettings([\n          `files:${volumeKey}:metadata`,\n          connector.resolvePath(path),\n        ]),\n      );\n\n      if (!result.ok) {\n        this._sendStatusError(res, result.status);\n        return;\n      }\n      res.json(result.data);\n    } catch (error) {\n      this._handleApiError(res, error, \"Metadata fetch failed\");\n    }\n  }\n\n  private async _handlePreview(\n    req: express.Request,\n    res: express.Response,\n    connector: FilesConnector,\n    volumeKey: string,\n  ): Promise<void> {\n    const path = req.query.path as string;\n\n    const valid = this._isValidPath(path);\n    if (valid !== true) {\n      res.status(400).json({ error: valid, plugin: this.name });\n      return;\n    }\n\n    if (!(await this._enforcePolicy(req, res, volumeKey, \"preview\", path)))\n      return;\n\n    try {\n      const result = await this.execute(\n        async () => connector.preview(getWorkspaceClient(), path),\n        this._readSettings([\n          `files:${volumeKey}:preview`,\n          connector.resolvePath(path),\n        ]),\n      );\n\n      if (!result.ok) {\n        this._sendStatusError(res, result.status);\n        return;\n      }\n      res.json(result.data);\n    } catch (error) {\n      this._handleApiError(res, error, \"Preview failed\");\n    }\n  }\n\n  private async _handleUpload(\n    req: express.Request,\n    res: express.Response,\n    connector: FilesConnector,\n    volumeKey: string,\n  ): Promise<void> {\n    const path = req.query.path as string;\n    const valid = this._isValidPath(path);\n    if (valid !== true) {\n      res.status(400).json({ error: valid, plugin: this.name });\n      return;\n    }\n\n    const volumeCfg = this.volumeConfigs[volumeKey];\n    const maxSize = volumeCfg.maxUploadSize ?? FILES_MAX_UPLOAD_SIZE;\n    const rawContentLength = req.headers[\"content-length\"];\n    let contentLength: number | undefined;\n\n    if (typeof rawContentLength === \"string\" && rawContentLength.length > 0) {\n      if (!/^\\d+$/.test(rawContentLength)) {\n        res.status(400).json({\n          error: \"Invalid Content-Length header.\",\n          plugin: this.name,\n        });\n        return;\n      }\n      contentLength = Number(rawContentLength);\n    }\n\n    if (\n      !(await this._enforcePolicy(req, res, volumeKey, \"upload\", path, {\n        size: contentLength,\n      }))\n    )\n      return;\n\n    if (contentLength !== undefined && contentLength > maxSize) {\n      res.status(413).json({\n        error: `File size (${contentLength} bytes) exceeds maximum allowed size (${maxSize} bytes).`,\n        plugin: this.name,\n      });\n      return;\n    }\n\n    logger.debug(req, \"Upload started: volume=%s path=%s\", volumeKey, path);\n\n    try {\n      const rawStream: ReadableStream<Uint8Array> = Readable.toWeb(req);\n\n      let bytesReceived = 0;\n      const webStream = rawStream.pipeThrough(\n        new TransformStream<Uint8Array, Uint8Array>({\n          transform(chunk, controller) {\n            bytesReceived += chunk.byteLength;\n            if (bytesReceived > maxSize) {\n              controller.error(\n                new Error(\n                  `Upload stream exceeds maximum allowed size (${maxSize} bytes)`,\n                ),\n              );\n              return;\n            }\n            controller.enqueue(chunk);\n          },\n        }),\n      );\n\n      logger.debug(\n        req,\n        \"Upload body received: volume=%s path=%s, size=%d bytes\",\n        volumeKey,\n        path,\n        contentLength ?? 0,\n      );\n      const settings: PluginExecutionSettings = {\n        default: FILES_WRITE_DEFAULTS,\n      };\n      const result = await this.trackWrite(() =>\n        this.execute(async () => {\n          await connector.upload(getWorkspaceClient(), path, webStream);\n          return { success: true as const };\n        }, settings),\n      );\n\n      this._invalidateListCache(volumeKey, path, connector);\n\n      if (!result.ok) {\n        logger.error(\n          req,\n          \"Upload failed: volume=%s path=%s, size=%d bytes\",\n          volumeKey,\n          path,\n          contentLength ?? 0,\n        );\n        this._sendStatusError(res, result.status);\n        return;\n      }\n\n      logger.debug(req, \"Upload complete: volume=%s path=%s\", volumeKey, path);\n      res.json(result.data);\n    } catch (error) {\n      if (\n        error instanceof Error &&\n        error.message.includes(\"exceeds maximum allowed size\")\n      ) {\n        res.status(413).json({ error: error.message, plugin: this.name });\n        return;\n      }\n      this._handleApiError(res, error, \"Upload failed\");\n    }\n  }\n\n  private async _handleMkdir(\n    req: express.Request,\n    res: express.Response,\n    connector: FilesConnector,\n    volumeKey: string,\n  ): Promise<void> {\n    const dirPath =\n      typeof req.body?.path === \"string\" ? req.body.path : undefined;\n\n    const valid = this._isValidPath(dirPath);\n    if (valid !== true) {\n      res.status(400).json({ error: valid, plugin: this.name });\n      return;\n    }\n\n    if (!(await this._enforcePolicy(req, res, volumeKey, \"mkdir\", dirPath)))\n      return;\n\n    try {\n      const settings: PluginExecutionSettings = {\n        default: FILES_WRITE_DEFAULTS,\n      };\n      const result = await this.trackWrite(() =>\n        this.execute(async () => {\n          await connector.createDirectory(getWorkspaceClient(), dirPath);\n          return { success: true as const };\n        }, settings),\n      );\n\n      this._invalidateListCache(volumeKey, dirPath, connector);\n\n      if (!result.ok) {\n        this._sendStatusError(res, result.status);\n        return;\n      }\n\n      res.json(result.data);\n    } catch (error) {\n      this._handleApiError(res, error, \"Create directory failed\");\n    }\n  }\n\n  private async _handleDelete(\n    req: express.Request,\n    res: express.Response,\n    connector: FilesConnector,\n    volumeKey: string,\n  ): Promise<void> {\n    const rawPath = req.query.path as string | undefined;\n\n    const valid = this._isValidPath(rawPath);\n    if (valid !== true) {\n      res.status(400).json({ error: valid, plugin: this.name });\n      return;\n    }\n    const path = rawPath as string;\n\n    if (!(await this._enforcePolicy(req, res, volumeKey, \"delete\", path)))\n      return;\n\n    try {\n      const settings: PluginExecutionSettings = {\n        default: FILES_WRITE_DEFAULTS,\n      };\n      const result = await this.trackWrite(() =>\n        this.execute(async () => {\n          await connector.delete(getWorkspaceClient(), path);\n          return { success: true as const };\n        }, settings),\n      );\n\n      this._invalidateListCache(volumeKey, path, connector);\n\n      if (!result.ok) {\n        this._sendStatusError(res, result.status);\n        return;\n      }\n\n      res.json(result.data);\n    } catch (error) {\n      this._handleApiError(res, error, \"Delete failed\");\n    }\n  }\n\n  /**\n   * Creates a VolumeAPI for a specific volume key.\n   *\n   * By default, enforces the volume's policy before each operation.\n   * Pass `bypassPolicy: true` to skip policy checks — useful for\n   * background jobs or migrations that should bypass user-facing policies.\n   *\n   * @security When `bypassPolicy` is `true`, no policy enforcement runs.\n   * Do not expose bypassed APIs to HTTP routes or end-user code paths.\n   */\n  protected createVolumeAPI(\n    volumeKey: string,\n    user: FilePolicyUser,\n    options?: { bypassPolicy?: boolean },\n  ): VolumeAPI {\n    const connector = this.volumeConnectors[volumeKey];\n    const noop = () => Promise.resolve();\n    const check = options?.bypassPolicy\n      ? noop\n      : (action: FileAction, path: string, overrides?: Partial<FileResource>) =>\n          this._checkPolicy(volumeKey, action, path, user, overrides);\n\n    return {\n      list: async (directoryPath?: string) => {\n        await check(\"list\", directoryPath ?? \"/\");\n        return connector.list(getWorkspaceClient(), directoryPath);\n      },\n      read: async (filePath: string, opts?: { maxSize?: number }) => {\n        await check(\"read\", filePath);\n        return connector.read(getWorkspaceClient(), filePath, opts);\n      },\n      download: async (filePath: string) => {\n        await check(\"download\", filePath);\n        return connector.download(getWorkspaceClient(), filePath);\n      },\n      exists: async (filePath: string) => {\n        await check(\"exists\", filePath);\n        return connector.exists(getWorkspaceClient(), filePath);\n      },\n      metadata: async (filePath: string) => {\n        await check(\"metadata\", filePath);\n        return connector.metadata(getWorkspaceClient(), filePath);\n      },\n      upload: async (\n        filePath: string,\n        contents: ReadableStream | Buffer | string,\n        opts?: { overwrite?: boolean },\n      ) => {\n        await check(\"upload\", filePath);\n        return connector.upload(getWorkspaceClient(), filePath, contents, opts);\n      },\n      createDirectory: async (directoryPath: string) => {\n        await check(\"mkdir\", directoryPath);\n        return connector.createDirectory(getWorkspaceClient(), directoryPath);\n      },\n      delete: async (filePath: string) => {\n        await check(\"delete\", filePath);\n        return connector.delete(getWorkspaceClient(), filePath);\n      },\n      preview: async (filePath: string) => {\n        await check(\"preview\", filePath);\n        return connector.preview(getWorkspaceClient(), filePath);\n      },\n    };\n  }\n\n  /**\n   * Builds the agent-tool registry entries for a single volume. One set of\n   * tools per configured volume, keyed by `${volumeKey}.${method}`.\n   *\n   * Each handler resolves the caller's identity from the current execution\n   * context (OBO user when the agent run is wrapped in `asUser(req)`, service\n   * principal otherwise in local dev) and dispatches through\n   * `createVolumeAPI(volumeKey, user)` so the volume's policy is enforced\n   * uniformly for agent and HTTP callers.\n   */\n  private _defineVolumeTools(volumeKey: string): ToolRegistry {\n    const buildUser = (): FilePolicyUser => {\n      const ctx = getExecutionContext();\n      return isUserContext(ctx)\n        ? { id: ctx.userId }\n        : { id: ctx.serviceUserId, isServicePrincipal: true };\n    };\n    const api = () => this.createVolumeAPI(volumeKey, buildUser());\n    return {\n      [`${volumeKey}.list`]: defineTool({\n        description: `List files and directories in the \"${volumeKey}\" volume`,\n        schema: z.object({\n          path: z\n            .string()\n            .optional()\n            .describe(\"Directory path to list (optional, defaults to root)\"),\n        }),\n        annotations: { effect: \"read\", requiresUserContext: true },\n        autoInheritable: true,\n        execute: (args, signal) => {\n          signal?.throwIfAborted();\n          return api().list(args.path);\n        },\n      }),\n      [`${volumeKey}.read`]: defineTool({\n        description: `Read a text file from the \"${volumeKey}\" volume`,\n        schema: z.object({\n          path: z.string().describe(\"File path to read\"),\n        }),\n        annotations: { effect: \"read\", requiresUserContext: true },\n        autoInheritable: true,\n        execute: (args, signal) => {\n          signal?.throwIfAborted();\n          return api().read(args.path);\n        },\n      }),\n      [`${volumeKey}.exists`]: defineTool({\n        description: `Check if a file or directory exists in the \"${volumeKey}\" volume`,\n        schema: z.object({\n          path: z.string().describe(\"Path to check\"),\n        }),\n        annotations: { effect: \"read\", requiresUserContext: true },\n        autoInheritable: true,\n        execute: (args, signal) => {\n          signal?.throwIfAborted();\n          return api().exists(args.path);\n        },\n      }),\n      [`${volumeKey}.metadata`]: defineTool({\n        description: `Get metadata (size, type, last modified) for a file in the \"${volumeKey}\" volume`,\n        schema: z.object({\n          path: z.string().describe(\"File path\"),\n        }),\n        annotations: { effect: \"read\", requiresUserContext: true },\n        autoInheritable: true,\n        execute: (args, signal) => {\n          signal?.throwIfAborted();\n          return api().metadata(args.path);\n        },\n      }),\n      [`${volumeKey}.upload`]: defineTool({\n        description: `Upload a text file to the \"${volumeKey}\" volume`,\n        schema: z.object({\n          path: z.string().describe(\"Destination file path\"),\n          contents: z.string().describe(\"File contents as a string\"),\n          overwrite: z\n            .boolean()\n            .optional()\n            .describe(\"Whether to overwrite existing file\"),\n        }),\n        annotations: { effect: \"destructive\", requiresUserContext: true },\n        execute: (args, signal) => {\n          signal?.throwIfAborted();\n          return api().upload(args.path, args.contents, {\n            overwrite: args.overwrite,\n          });\n        },\n      }),\n      [`${volumeKey}.delete`]: defineTool({\n        description: `Delete a file from the \"${volumeKey}\" volume`,\n        schema: z.object({\n          path: z.string().describe(\"File path to delete\"),\n        }),\n        annotations: { effect: \"destructive\", requiresUserContext: true },\n        execute: (args, signal) => {\n          signal?.throwIfAborted();\n          return api().delete(args.path);\n        },\n      }),\n    };\n  }\n\n  private inflightWrites = 0;\n\n  private trackWrite<T>(fn: () => Promise<T>): Promise<T> {\n    this.inflightWrites++;\n    return fn().finally(() => {\n      this.inflightWrites--;\n    });\n  }\n\n  async shutdown(): Promise<void> {\n    // Wait up to 10 seconds for in-flight write operations to finish\n    const deadline = Date.now() + 10_000;\n    while (this.inflightWrites > 0 && Date.now() < deadline) {\n      logger.info(\n        \"Waiting for %d in-flight write(s) to complete before shutdown…\",\n        this.inflightWrites,\n      );\n      await new Promise((resolve) => setTimeout(resolve, 500));\n    }\n    if (this.inflightWrites > 0) {\n      logger.warn(\n        \"Shutdown deadline reached with %d in-flight write(s) still pending.\",\n        this.inflightWrites,\n      );\n    }\n    this.streamManager.abortAll();\n  }\n\n  getAgentTools(): AgentToolDefinition[] {\n    return toolsFromRegistry(this.tools);\n  }\n\n  async executeAgentTool(\n    name: string,\n    args: unknown,\n    signal?: AbortSignal,\n  ): Promise<unknown> {\n    return executeFromRegistry(this.tools, name, args, signal);\n  }\n\n  toolkit(opts?: import(\"../../core/agent/types\").ToolkitOptions) {\n    return buildToolkitEntries(this.name, this.tools, opts);\n  }\n\n  /**\n   * Returns the programmatic API for the Files plugin.\n   * Callable with a volume key to get a volume-scoped handle.\n   *\n   * All operations execute as the service principal.\n   * Use policies to control per-user access.\n   *\n   * @example\n   * ```ts\n   * // Service principal access\n   * appKit.files(\"uploads\").list()\n   *\n   * // With policy: pass user identity for access control\n   * appKit.files(\"uploads\").asUser(req).list()\n   * ```\n   */\n  exports(): FilesExport {\n    const resolveVolume = (volumeKey: string): VolumeHandle => {\n      if (!this.volumeKeys.includes(volumeKey)) {\n        throw new Error(\n          `Unknown volume \"${volumeKey}\". Available volumes: ${this.volumeKeys.join(\", \")}`,\n        );\n      }\n\n      // Lazy user resolution: getCurrentUserId() is called when a method\n      // is invoked (policy check), not when exports() is called.\n      const spUser: FilePolicyUser = {\n        get id() {\n          return getCurrentUserId();\n        },\n        isServicePrincipal: true,\n      };\n      const spApi = this.createVolumeAPI(volumeKey, spUser);\n\n      return {\n        ...spApi,\n        asUser: (req: express.Request) => {\n          const user = this._extractUser(req);\n          return this.createVolumeAPI(volumeKey, user);\n        },\n      };\n    };\n\n    const filesExport = ((volumeKey: string) =>\n      resolveVolume(volumeKey)) as FilesExport;\n    filesExport.volume = resolveVolume;\n\n    return filesExport;\n  }\n\n  clientConfig(): Record<string, unknown> {\n    return { volumes: this.volumeKeys };\n  }\n}\n\n/**\n * @internal\n */\nexport const files = Object.assign(toPlugin(FilesPlugin), { policy });\n"],"mappings":"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"}
+{"version":3,"file":"plugin.js","names":["manifest","files"],"sources":["../../../src/plugins/files/plugin.ts"],"sourcesContent":["import { STATUS_CODES } from \"node:http\";\nimport { Readable } from \"node:stream\";\nimport { ApiError } from \"@databricks/sdk-experimental\";\nimport type express from \"express\";\nimport type {\n  AgentToolDefinition,\n  IAppRouter,\n  PluginExecutionSettings,\n  ToolProvider,\n} from \"shared\";\nimport { z } from \"zod\";\nimport {\n  contentTypeFromPath,\n  FILES_MAX_READ_SIZE,\n  FilesConnector,\n  isSafeInlineContentType,\n  runWithFilesSpanAttributes,\n  validateCustomContentTypes,\n} from \"../../connectors/files\";\nimport {\n  getCurrentUserId,\n  getExecutionContext,\n  getWorkspaceClient,\n  runInUserContext,\n  ServiceContext,\n  type UserContext,\n} from \"../../context\";\nimport { isUserContext } from \"../../context/user-context\";\nimport { buildToolkitEntries } from \"../../core/agent/build-toolkit\";\nimport {\n  defineTool,\n  executeFromRegistry,\n  type ToolRegistry,\n  toolsFromRegistry,\n} from \"../../core/agent/tools/define-tool\";\nimport { AuthenticationError } from \"../../errors\";\nimport { createLogger } from \"../../logging/logger\";\nimport { Plugin, toPlugin } from \"../../plugin\";\nimport type { PluginManifest, ResourceRequirement } from \"../../registry\";\nimport { ResourceType } from \"../../registry\";\nimport {\n  FILES_DOWNLOAD_DEFAULTS,\n  FILES_MAX_UPLOAD_SIZE,\n  FILES_READ_DEFAULTS,\n  FILES_WRITE_DEFAULTS,\n} from \"./defaults\";\nimport { parentDirectory, sanitizeFilename } from \"./helpers\";\nimport manifest from \"./manifest.json\";\nimport {\n  type FileAction,\n  type FilePolicyUser,\n  type FileResource,\n  PolicyDeniedError,\n  policy,\n} from \"./policy\";\nimport type {\n  FilesExport,\n  IFilesConfig,\n  VolumeAPI,\n  VolumeConfig,\n  VolumeHandle,\n} from \"./types\";\n\nconst logger = createLogger(\"files\");\n\nexport class FilesPlugin extends Plugin implements ToolProvider {\n  name = \"files\";\n\n  /** Plugin manifest declaring metadata and resource requirements. */\n  static manifest = manifest as PluginManifest;\n  protected static description = \"Files plugin for Databricks file operations\";\n  protected declare config: IFilesConfig;\n\n  private volumeConnectors: Record<string, FilesConnector> = {};\n  private volumeConfigs: Record<string, VolumeConfig> = {};\n  private volumeKeys: string[] = [];\n  private tools: ToolRegistry = {};\n\n  /**\n   * Scans `process.env` for `DATABRICKS_VOLUME_*` keys and merges them with\n   * any explicitly configured volumes. Explicit config wins for per-volume\n   * overrides; auto-discovered volumes get default `{}` config.\n   */\n  static discoverVolumes(config: IFilesConfig): Record<string, VolumeConfig> {\n    const explicit = config.volumes ?? {};\n    const discovered: Record<string, VolumeConfig> = {};\n\n    const prefix = \"DATABRICKS_VOLUME_\";\n    for (const key of Object.keys(process.env)) {\n      if (!key.startsWith(prefix)) continue;\n      const suffix = key.slice(prefix.length);\n      if (!suffix) continue;\n      if (!process.env[key]) continue;\n      const volumeKey = suffix.toLowerCase();\n      if (!(volumeKey in explicit)) {\n        discovered[volumeKey] = {};\n      }\n    }\n\n    return { ...discovered, ...explicit };\n  }\n\n  /**\n   * Generates resource requirements dynamically from discovered + configured volumes.\n   * Each volume key maps to a `DATABRICKS_VOLUME_{KEY_UPPERCASE}` env var.\n   *\n   * ## Per-volume permission scope (SP vs OBO)\n   *\n   * The returned manifest entries describe a single permission grant per\n   * volume, but the *grantee* depends on the volume's `auth` setting at\n   * runtime — and that distinction is **not** expressed in the manifest\n   * today:\n   *\n   * - **Service-principal volumes** (the default, `auth: \"service-principal\"`):\n   *   the app's service principal needs `WRITE_VOLUME` (or read-equivalent)\n   *   on the UC volume. This matches the manifest entry as written.\n   * - **On-behalf-of-user volumes** (`auth: \"on-behalf-of-user\"`): SDK calls\n   *   execute as the **end user**, so the *user* — not the SP — must hold\n   *   `WRITE_VOLUME` (or read-equivalent) on the UC volume. The SP only\n   *   needs to be allowed to mint user-token requests; it does not need\n   *   direct volume permissions.\n   *\n   * The static manifest cannot currently express this per-volume split, so\n   * callers configuring OBO volumes must communicate the per-user permission\n   * requirement out-of-band (docs, runbooks, deployment scripts) until the\n   * manifest schema gains a per-volume auth scope field.\n   */\n  static getResourceRequirements(config: IFilesConfig): ResourceRequirement[] {\n    const volumes = FilesPlugin.discoverVolumes(config);\n    // TODO: extend plugin-manifest.schema.json to express per-volume auth\n    // scope so OBO volumes can declare end-user-required permissions in the\n    // manifest itself.\n    return Object.keys(volumes).map((key) => ({\n      type: ResourceType.VOLUME,\n      alias: `volume-${key}`,\n      resourceKey: `volume-${key}`,\n      description: `Unity Catalog Volume for \"${key}\" file storage`,\n      permission: \"WRITE_VOLUME\",\n      fields: {\n        path: {\n          env: `DATABRICKS_VOLUME_${key.toUpperCase()}`,\n          description: `Volume path for \"${key}\" (e.g. /Volumes/catalog/schema/volume_name)`,\n        },\n      },\n      required: true,\n    }));\n  }\n\n  /**\n   * Extraction for `VolumeHandle.asUser(req)`. In production we require BOTH\n   * `x-forwarded-user` and `x-forwarded-access-token`, and throw\n   * `AuthenticationError.missingToken` if either is missing — otherwise a\n   * request with only `x-forwarded-user: alice` would let policies see Alice\n   * as a \"real user\" (`isServicePrincipal: false`) while the SDK call below\n   * falls through to the SP client because `_buildUserContextOrNull` returns\n   * `null`. Net effect: policy approves the user, SDK runs as SP, privilege\n   * confusion (CWE-639/863).\n   *\n   * In development (`NODE_ENV === \"development\"`) we keep a local-loop\n   * convenience: if either header is missing we emit a single warning and\n   * return a policy user explicitly marked `isServicePrincipal: true`, so\n   * even in dev a `usersOnly`-style policy that gates on\n   * `!user.isServicePrincipal` cannot be tricked. The matching SDK execution\n   * path also falls through to the SP client (no `runInUserContext` wrap),\n   * so the policy user and the SDK identity stay aligned.\n   */\n  private _extractUser(req: express.Request): FilePolicyUser {\n    const userId = req.header(\"x-forwarded-user\")?.trim();\n    const token = req.header(\"x-forwarded-access-token\")?.trim();\n    if (userId && token) return { id: userId, isServicePrincipal: false };\n    if (process.env.NODE_ENV === \"development\") {\n      logger.warn(\n        \"asUser(req) called without complete x-forwarded-user + x-forwarded-access-token headers — \" +\n          \"falling back to service principal identity (dev mode). \" +\n          \"In production this request would 401.\",\n      );\n      return { id: getCurrentUserId(), isServicePrincipal: true };\n    }\n    if (!token) {\n      throw AuthenticationError.missingToken(\n        \"Missing x-forwarded-access-token header for asUser(req). Both x-forwarded-user and x-forwarded-access-token are required.\",\n      );\n    }\n    throw AuthenticationError.missingToken(\n      \"Missing x-forwarded-user header. Cannot resolve user ID for asUser(req).\",\n    );\n  }\n\n  /**\n   * Extraction for OBO (on-behalf-of-user) volumes on the HTTP path. Both the\n   * `x-forwarded-access-token` and `x-forwarded-user` headers must be present\n   * for a valid end-user identity. When the token is missing:\n   * - In production we throw `AuthenticationError.missingToken` so the route\n   *   responds with 401 (no SDK call is made).\n   * - In development (`NODE_ENV === \"development\"`) we emit a single warning\n   *   and fall back to the service principal identity so local testing\n   *   without a reverse proxy continues to work.\n   */\n  private _extractOboUser(req: express.Request): FilePolicyUser {\n    const token = req.header(\"x-forwarded-access-token\")?.trim();\n    const userId = req.header(\"x-forwarded-user\")?.trim();\n    if (token && userId) {\n      return { id: userId, isServicePrincipal: false };\n    }\n    if (!token && process.env.NODE_ENV === \"development\") {\n      logger.warn(\n        \"OBO volume requested without x-forwarded-access-token — falling back to service principal identity (dev mode). \" +\n          \"In production this request would 401.\",\n      );\n      return { id: getCurrentUserId(), isServicePrincipal: true };\n    }\n    throw AuthenticationError.missingToken(\n      !token\n        ? \"Missing x-forwarded-access-token header for on-behalf-of-user volume.\"\n        : \"Missing x-forwarded-user header for on-behalf-of-user volume.\",\n    );\n  }\n\n  /**\n   * Check the policy for a volume. No-op if no policy is configured.\n   * Throws `PolicyDeniedError` if denied.\n   */\n  private async _checkPolicy(\n    volumeKey: string,\n    action: FileAction,\n    path: string,\n    user: FilePolicyUser,\n    resourceOverrides?: Partial<FileResource>,\n  ): Promise<void> {\n    const policyFn = this.volumeConfigs[volumeKey]?.policy;\n    if (typeof policyFn !== \"function\") return;\n\n    const resource: FileResource = {\n      path,\n      volume: volumeKey,\n      ...resourceOverrides,\n    };\n    const allowed = await policyFn(action, resource, user);\n    if (!allowed) {\n      const userId = user.isServicePrincipal ? \"<service-principal>\" : user.id;\n      logger.warn(\n        'Policy denied \"%s\" on volume \"%s\" for user \"%s\"',\n        action,\n        volumeKey,\n        userId,\n      );\n      throw new PolicyDeniedError(action, volumeKey);\n    }\n  }\n\n  /**\n   * HTTP-level wrapper around `_checkPolicy`.\n   * Selects the policy user based on the volume's auth mode (resolved via\n   * `_resolveAuth`):\n   * - `\"service-principal\"` (default): use the `x-forwarded-user` header when\n   *   present, otherwise fall back to the SP identity (legacy behavior).\n   * - `\"on-behalf-of-user\"`: require `x-forwarded-access-token` (and the\n   *   matching `x-forwarded-user`); 401 in production when missing,\n   *   dev-fallback to SP identity in development.\n   * Then runs the volume policy (403 on denial, 500 on unexpected error).\n   * Returns `true` if the request may proceed, `false` if a response was sent.\n   *\n   * NOTE: This method only selects which identity the *policy* sees. The\n   * matching SDK execution identity is selected separately by\n   * `_resolveAuthForRequest` and applied via `_runWithAuth` /\n   * `runInUserContext` in each handler. The two selections are designed to\n   * converge on the same identity per the policy-user matrix in the docs —\n   * see `docs/docs/plugins/files.md#policy-user-matrix`.\n   */\n  private async _enforcePolicy(\n    req: express.Request,\n    res: express.Response,\n    volumeKey: string,\n    action: FileAction,\n    path: string,\n    resourceOverrides?: Partial<FileResource>,\n  ): Promise<boolean> {\n    let user: FilePolicyUser;\n    try {\n      const auth = this._resolveAuth(volumeKey);\n      if (auth === \"on-behalf-of-user\") {\n        user = this._extractOboUser(req);\n      } else {\n        const headerUserId = req.header(\"x-forwarded-user\")?.trim();\n        if (headerUserId) {\n          user = { id: headerUserId };\n        } else {\n          logger.debug(\n            \"No x-forwarded-user header — proceeding with service principal identity for policy evaluation.\",\n          );\n          user = { id: getCurrentUserId(), isServicePrincipal: true };\n        }\n      }\n    } catch (error) {\n      if (error instanceof AuthenticationError) {\n        logger.warn(\n          \"Authentication failed during policy evaluation for volume %s: %O\",\n          volumeKey,\n          error,\n        );\n        res.status(401).json({ error: \"Unauthorized\", plugin: this.name });\n        return false;\n      }\n      throw error;\n    }\n\n    try {\n      await this._checkPolicy(volumeKey, action, path, user, resourceOverrides);\n    } catch (error) {\n      if (error instanceof PolicyDeniedError) {\n        res.status(403).json({ error: error.message, plugin: this.name });\n        return false;\n      }\n      // A crashing policy is treated as a server error (fail closed).\n      logger.error(\"Policy function threw on volume %s: %O\", volumeKey, error);\n      res.status(500).json({\n        error: \"Policy evaluation failed\",\n        plugin: this.name,\n      });\n      return false;\n    }\n\n    return true;\n  }\n\n  constructor(config: IFilesConfig) {\n    super(config);\n    this.config = config;\n\n    if (config.customContentTypes) {\n      validateCustomContentTypes(config.customContentTypes);\n    }\n\n    const volumes = FilesPlugin.discoverVolumes(config);\n    this.volumeKeys = Object.keys(volumes);\n\n    for (const key of this.volumeKeys) {\n      const volumeCfg = volumes[key];\n      const envVar = `DATABRICKS_VOLUME_${key.toUpperCase()}`;\n      const volumePath = process.env[envVar];\n\n      // Merge per-volume config with plugin-level defaults\n      const mergedConfig: VolumeConfig = {\n        maxUploadSize: volumeCfg.maxUploadSize ?? config.maxUploadSize,\n        maxReadSize: volumeCfg.maxReadSize ?? config.maxReadSize,\n        customContentTypes:\n          volumeCfg.customContentTypes ?? config.customContentTypes,\n        policy: volumeCfg.policy ?? policy.publicRead(),\n        auth: volumeCfg.auth,\n      };\n      this.volumeConfigs[key] = mergedConfig;\n\n      this.volumeConnectors[key] = new FilesConnector({\n        defaultVolume: volumePath,\n        timeout: config.timeout,\n        telemetry: config.telemetry,\n        customContentTypes: mergedConfig.customContentTypes,\n      });\n\n      Object.assign(this.tools, this._defineVolumeTools(key));\n\n      // Warn at startup for volumes without an explicit policy\n      if (!volumeCfg.policy) {\n        logger.warn(\n          'Volume \"%s\" has no explicit policy — defaulting to publicRead(). ' +\n            \"This also matches header-less HTTP requests (which run as the service principal). \" +\n            \"Set a policy in files({ volumes: { %s: { policy: ... } } }) to silence this warning.\",\n          key,\n          key,\n        );\n      }\n    }\n  }\n\n  injectRoutes(router: IAppRouter) {\n    this.route(router, {\n      name: \"volumes\",\n      method: \"get\",\n      path: \"/volumes\",\n      handler: async (_req: express.Request, res: express.Response) => {\n        res.json({ volumes: this.volumeKeys });\n      },\n    });\n\n    this.route(router, {\n      name: \"list\",\n      method: \"get\",\n      path: \"/:volumeKey/list\",\n      handler: async (req: express.Request, res: express.Response) => {\n        const { connector, volumeKey } = this._resolveVolume(req, res);\n        if (!connector) return;\n        await this._handleList(req, res, connector, volumeKey);\n      },\n    });\n\n    this.route(router, {\n      name: \"read\",\n      method: \"get\",\n      path: \"/:volumeKey/read\",\n      handler: async (req: express.Request, res: express.Response) => {\n        const { connector, volumeKey } = this._resolveVolume(req, res);\n        if (!connector) return;\n        await this._handleRead(req, res, connector, volumeKey);\n      },\n    });\n\n    this.route(router, {\n      name: \"download\",\n      method: \"get\",\n      path: \"/:volumeKey/download\",\n      handler: async (req: express.Request, res: express.Response) => {\n        const { connector, volumeKey } = this._resolveVolume(req, res);\n        if (!connector) return;\n        await this._handleDownload(req, res, connector, volumeKey);\n      },\n    });\n\n    this.route(router, {\n      name: \"raw\",\n      method: \"get\",\n      path: \"/:volumeKey/raw\",\n      handler: async (req: express.Request, res: express.Response) => {\n        const { connector, volumeKey } = this._resolveVolume(req, res);\n        if (!connector) return;\n        await this._handleRaw(req, res, connector, volumeKey);\n      },\n    });\n\n    this.route(router, {\n      name: \"exists\",\n      method: \"get\",\n      path: \"/:volumeKey/exists\",\n      handler: async (req: express.Request, res: express.Response) => {\n        const { connector, volumeKey } = this._resolveVolume(req, res);\n        if (!connector) return;\n        await this._handleExists(req, res, connector, volumeKey);\n      },\n    });\n\n    this.route(router, {\n      name: \"metadata\",\n      method: \"get\",\n      path: \"/:volumeKey/metadata\",\n      handler: async (req: express.Request, res: express.Response) => {\n        const { connector, volumeKey } = this._resolveVolume(req, res);\n        if (!connector) return;\n        await this._handleMetadata(req, res, connector, volumeKey);\n      },\n    });\n\n    this.route(router, {\n      name: \"preview\",\n      method: \"get\",\n      path: \"/:volumeKey/preview\",\n      handler: async (req: express.Request, res: express.Response) => {\n        const { connector, volumeKey } = this._resolveVolume(req, res);\n        if (!connector) return;\n        await this._handlePreview(req, res, connector, volumeKey);\n      },\n    });\n\n    this.route(router, {\n      name: \"upload\",\n      method: \"post\",\n      path: \"/:volumeKey/upload\",\n      skipBodyParsing: true,\n      handler: async (req: express.Request, res: express.Response) => {\n        const { connector, volumeKey } = this._resolveVolume(req, res);\n        if (!connector) return;\n        await this._handleUpload(req, res, connector, volumeKey);\n      },\n    });\n\n    this.route(router, {\n      name: \"mkdir\",\n      method: \"post\",\n      path: \"/:volumeKey/mkdir\",\n      handler: async (req: express.Request, res: express.Response) => {\n        const { connector, volumeKey } = this._resolveVolume(req, res);\n        if (!connector) return;\n        await this._handleMkdir(req, res, connector, volumeKey);\n      },\n    });\n\n    this.route(router, {\n      name: \"delete\",\n      method: \"delete\",\n      path: \"/:volumeKey\",\n      handler: async (req: express.Request, res: express.Response) => {\n        const { connector, volumeKey } = this._resolveVolume(req, res);\n        if (!connector) return;\n        await this._handleDelete(req, res, connector, volumeKey);\n      },\n    });\n  }\n\n  /**\n   * Resolve `:volumeKey` from the request. Returns the connector and key,\n   * or sends a 404 and returns `{ connector: undefined }`.\n   */\n  private _resolveVolume(\n    req: express.Request,\n    res: express.Response,\n  ):\n    | { connector: FilesConnector; volumeKey: string }\n    | { connector: undefined; volumeKey: undefined } {\n    const volumeKey = req.params.volumeKey;\n    const connector = this.volumeConnectors[volumeKey];\n    if (!connector) {\n      const safeKey = volumeKey.replace(/[^a-zA-Z0-9_-]/g, \"\");\n      res.status(404).json({\n        error: `Unknown volume \"${safeKey}\"`,\n        plugin: this.name,\n      });\n      return { connector: undefined, volumeKey: undefined };\n    }\n    return { connector, volumeKey };\n  }\n\n  /**\n   * Extract `req.query.path` as a single string when present.\n   *\n   * Express coerces repeated query parameters (`?path=a&path=b`) to a string\n   * array and dotted/nested params (`?path[k]=v`) to an object. Reject those\n   * with `400` instead of letting non-string values reach `_isValidPath` /\n   * `connector.resolvePath`, which would misbehave on arrays or objects.\n   *\n   * Returns `{ path }` (with `path` either a string or `undefined` when the\n   * query parameter was absent) on success. Returns `undefined` and writes a\n   * `400` response when the value is not a single string — callers must\n   * check the return for `undefined` before continuing.\n   */\n  private _readPathQuery(\n    req: express.Request,\n    res: express.Response,\n  ): { path: string | undefined } | undefined {\n    const value = req.query.path;\n    if (value === undefined || typeof value === \"string\") {\n      return { path: value };\n    }\n    res.status(400).json({\n      error: \"path query parameter must be a single string\",\n      plugin: this.name,\n    });\n    return undefined;\n  }\n\n  /**\n   * Validate a file/directory path from user input.\n   * Returns `true` if valid, or an error message string if invalid.\n   */\n  private _isValidPath(path: string | undefined): true | string {\n    if (!path) return \"path is required\";\n    if (path.length > 4096)\n      return `path exceeds maximum length of 4096 characters (got ${path.length})`;\n    if (path.includes(\"\\0\")) return \"path must not contain null bytes\";\n    return true;\n  }\n\n  private _readSettings(\n    cacheKey: (string | number | object)[],\n    authMode: \"service-principal\" | \"on-behalf-of-user\",\n  ): PluginExecutionSettings {\n    // OBO volumes: disable list/read cache. The cache layer is keyed by\n    // `getCurrentUserId()`, so user A's writes can only invalidate user A's\n    // cache entry — user B would continue to see stale data for the same\n    // volume/path until TTL. Disabling caching trades read performance for\n    // correctness; the alternative is a per-(volume, path) generation\n    // counter folded into the cache key on writes (a future enhancement).\n    const isObo = authMode === \"on-behalf-of-user\";\n    const cache = isObo\n      ? { ...FILES_READ_DEFAULTS.cache, enabled: false, cacheKey }\n      : { ...FILES_READ_DEFAULTS.cache, cacheKey };\n    return {\n      default: {\n        ...FILES_READ_DEFAULTS,\n        cache,\n        telemetryInterceptor: {\n          attributes: this._authModeAttributes(authMode),\n        },\n      },\n    };\n  }\n\n  private _writeSettings(\n    authMode: \"service-principal\" | \"on-behalf-of-user\",\n  ): PluginExecutionSettings {\n    return {\n      default: {\n        ...FILES_WRITE_DEFAULTS,\n        telemetryInterceptor: {\n          attributes: this._authModeAttributes(authMode),\n        },\n      },\n    };\n  }\n\n  private _downloadSettings(\n    authMode: \"service-principal\" | \"on-behalf-of-user\",\n  ): PluginExecutionSettings {\n    return {\n      default: {\n        ...FILES_DOWNLOAD_DEFAULTS,\n        telemetryInterceptor: {\n          attributes: this._authModeAttributes(authMode),\n        },\n      },\n    };\n  }\n\n  /**\n   * Invalidate cached list entries for a directory after a write operation.\n   * Must produce the SAME cache-key shape that `_handleList` stored under.\n   * `_handleList` builds its key from `req.query.path`: when `path` is\n   * provided it uses `connector.resolvePath(path)`, otherwise it uses the\n   * sentinel `\"__root__\"`. The invalidation here must derive the matching\n   * directory from the FILE path being written:\n   *\n   * - `\"/Volumes/c/s/v/foo/bar.txt\"` → `parentDirectory` returns\n   *   `\"/Volumes/c/s/v/foo\"` → resolved path key.\n   * - `\"/bar.txt\"` and `\"bar.txt\"` → root-level files: matching list cache\n   *   was a rootless `list()` call → `\"__root__\"` sentinel.\n   * - `\"/Volumes/c/s/v/bar.txt\"` → `parentDirectory` returns the UC\n   *   volume path (`\"/Volumes/c/s/v\"`). That's also root-level — a\n   *   rootless `list()` would have cached under `\"__root__\"`, while\n   *   `list(\"/Volumes/c/s/v\")` and `list(\"/Volumes/c/s/v/\")` would have\n   *   cached under the volume path with and without trailing slash. All\n   *   three are invalidated.\n   *\n   * On OBO volumes the read cache is disabled (see `_readSettings`), so\n   * invalidation is a no-op here for `mode === \"on-behalf-of-user\"`. The\n   * cache layer is keyed by `getCurrentUserId()`, so user A's writes can\n   * only invalidate user A's cache entry — user B would otherwise see stale\n   * data for the same volume/path until TTL. Disabling the cache on OBO\n   * trades read performance for correctness; the alternative is a\n   * per-(volume, path) generation counter folded into the cache key on\n   * writes (a future enhancement).\n   *\n   * Best-effort: a thrown `connector.resolvePath` (e.g. on malformed input)\n   * is swallowed here. Invalidation is purely an optimization signal — a\n   * missed delete only costs read freshness, not correctness, and\n   * propagating the error would convert a successful write into an HTTP\n   * 500.\n   *\n   * Returns a `Promise<void>`; callers MUST `await` this before sending the\n   * HTTP success response so a follow-up `GET /list` issued in the same tick\n   * cannot race the underlying `cache.delete()` and observe stale data.\n   */\n  private async _invalidateListCache(\n    volumeKey: string,\n    writtenPath: string,\n    connector: FilesConnector,\n    mode: \"service-principal\" | \"on-behalf-of-user\" = \"service-principal\",\n  ): Promise<void> {\n    if (mode === \"on-behalf-of-user\") {\n      // OBO read cache is disabled — nothing to invalidate. Skipping here\n      // also prevents accidentally caching a wrong-namespace delete that\n      // would mask the missing cross-user invalidation if the cache were\n      // ever re-enabled.\n      return;\n    }\n    const parent = parentDirectory(writtenPath);\n    const userKey = getCurrentUserId();\n    const tryDelete = async (segment: string): Promise<void> => {\n      try {\n        await this.cache.delete(\n          this.cache.generateKey([`files:${volumeKey}:list`, segment], userKey),\n        );\n      } catch (err) {\n        logger.debug(\n          \"List-cache invalidation failed for volume=%s segment=%s: %O\",\n          volumeKey,\n          segment,\n          err,\n        );\n      }\n    };\n\n    // Compute the UC volume root (e.g. `\"/Volumes/c/s/v\"`) when the\n    // connector has a default volume. Used both to detect absolute-path\n    // root-level writes and to invalidate every cache key shape that\n    // mapped to the volume root listing. `resolvePath(\"\")` returns\n    // `\"<defaultVolume>/\"`; strip the trailing slash for comparison.\n    let volumeRoot: string | null = null;\n    try {\n      volumeRoot = connector.resolvePath(\"\").replace(/\\/+$/, \"\");\n    } catch (err) {\n      logger.debug(\n        'List-cache invalidation: resolvePath(\"\") failed for volume=%s: %O',\n        volumeKey,\n        err,\n      );\n    }\n\n    // Root-level when the parent is empty/`\"/\"` (relative or `/foo.txt`)\n    // OR when the parent equals the UC volume root (absolute UC path\n    // `\"/Volumes/c/s/v/foo.txt\"`).\n    const isRootLevel =\n      !parent ||\n      parent === \"/\" ||\n      (volumeRoot !== null && parent === volumeRoot);\n\n    if (isRootLevel) {\n      // A rootless `list()` cached under `\"__root__\"`. Listings via\n      // `?path=<volumeRoot>` or `?path=<volumeRoot>/` cached under the\n      // volume path with/without trailing slash. Invalidate every shape.\n      await tryDelete(\"__root__\");\n      if (volumeRoot !== null) {\n        await tryDelete(volumeRoot);\n        await tryDelete(`${volumeRoot}/`);\n      }\n      return;\n    }\n\n    let resolved: string;\n    try {\n      resolved = connector.resolvePath(parent);\n    } catch (err) {\n      logger.debug(\n        \"List-cache invalidation: resolvePath(%s) failed for volume=%s: %O\",\n        parent,\n        volumeKey,\n        err,\n      );\n      return;\n    }\n    await tryDelete(resolved);\n  }\n\n  private _handleApiError(\n    res: express.Response,\n    error: unknown,\n    fallbackMessage: string,\n  ): void {\n    if (error instanceof PolicyDeniedError) {\n      res.status(403).json({\n        error: error.message,\n        plugin: this.name,\n      });\n      return;\n    }\n    if (error instanceof AuthenticationError) {\n      logger.warn(\"Authentication failed in %s: %O\", this.name, error);\n      res.status(401).json({ error: \"Unauthorized\", plugin: this.name });\n      return;\n    }\n    if (error instanceof ApiError) {\n      const status = error.statusCode ?? 500;\n      if (status >= 400 && status < 500) {\n        // Don't reflect raw SDK error.message — it can leak internal volume\n        // paths, hostnames, or principal names. Use the standard HTTP status\n        // text for the public body and log the full error server-side.\n        logger.warn(\"Upstream %d in %s: %O\", status, this.name, error);\n        res.status(status).json({\n          error: STATUS_CODES[status] ?? \"Client Error\",\n          statusCode: status,\n          plugin: this.name,\n        });\n        return;\n      }\n      logger.error(\"Upstream server error in %s: %O\", this.name, error);\n      res.status(500).json({ error: fallbackMessage, plugin: this.name });\n      return;\n    }\n    logger.error(\"Unhandled error in %s: %O\", this.name, error);\n    res.status(500).json({ error: fallbackMessage, plugin: this.name });\n  }\n\n  private _sendStatusError(res: express.Response, status: number): void {\n    res.status(status).json({\n      error: STATUS_CODES[status] ?? \"Unknown Error\",\n      plugin: this.name,\n    });\n  }\n\n  private async _handleList(\n    req: express.Request,\n    res: express.Response,\n    connector: FilesConnector,\n    volumeKey: string,\n  ): Promise<void> {\n    const query = this._readPathQuery(req, res);\n    if (!query) return;\n    const path = query.path;\n\n    if (!(await this._enforcePolicy(req, res, volumeKey, \"list\", path ?? \"/\")))\n      return;\n\n    const { mode, userCtx } = this._resolveAuthForRequest(req, volumeKey);\n    await this._runWithAuth(userCtx, async () => {\n      try {\n        const result = await this.execute(\n          async () => connector.list(getWorkspaceClient(), path),\n          this._readSettings(\n            [\n              `files:${volumeKey}:list`,\n              path ? connector.resolvePath(path) : \"__root__\",\n            ],\n            mode,\n          ),\n        );\n\n        if (!result.ok) {\n          this._sendStatusError(res, result.status);\n          return;\n        }\n        res.json(result.data);\n      } catch (error) {\n        this._handleApiError(res, error, \"List failed\");\n      }\n    });\n  }\n\n  private async _handleRead(\n    req: express.Request,\n    res: express.Response,\n    connector: FilesConnector,\n    volumeKey: string,\n  ): Promise<void> {\n    const query = this._readPathQuery(req, res);\n    if (!query) return;\n    const rawPath = query.path;\n\n    const valid = this._isValidPath(rawPath);\n    if (valid !== true) {\n      res.status(400).json({ error: valid, plugin: this.name });\n      return;\n    }\n    const path = rawPath as string;\n\n    if (!(await this._enforcePolicy(req, res, volumeKey, \"read\", path))) return;\n\n    const volumeCfg = this.volumeConfigs[volumeKey];\n    const maxReadSize = volumeCfg.maxReadSize ?? FILES_MAX_READ_SIZE;\n    const { mode, userCtx } = this._resolveAuthForRequest(req, volumeKey);\n\n    await this._runWithAuth(userCtx, async () => {\n      try {\n        // Drain the file body into a memory buffer capped at `maxReadSize`.\n        // `/read` is for small text reads — clients wanting large or\n        // streaming bodies use `/download` or `/raw`. Buffering preserves\n        // the all-or-nothing contract: if the file exceeds the cap we\n        // respond 413 atomically without leaking a partial 200 body.\n        // Uses download-tier settings (no cache) — `/read` no longer\n        // participates in the read-tier cache. Programmatic callers wanting\n        // a cached small-file read should use the SDK\n        // `volume.read(path, { maxSize })` method directly.\n        const response = await this.execute(\n          async () => connector.download(getWorkspaceClient(), path),\n          this._downloadSettings(mode),\n        );\n        if (!response.ok) {\n          this._sendStatusError(res, response.status);\n          return;\n        }\n        if (!response.data.contents) {\n          res.type(\"text/plain\").send(\"\");\n          return;\n        }\n\n        const reader = response.data.contents.getReader();\n        const chunks: Uint8Array[] = [];\n        let bytesRead = 0;\n        try {\n          while (true) {\n            const { value, done } = await reader.read();\n            if (done) break;\n            bytesRead += value.byteLength;\n            if (bytesRead > maxReadSize) {\n              res.status(413).json({\n                error: `File exceeds maxReadSize (${maxReadSize} bytes). Use /download for large files.`,\n                plugin: this.name,\n              });\n              try {\n                await reader.cancel();\n              } catch {\n                // best-effort cleanup\n              }\n              return;\n            }\n            chunks.push(value);\n          }\n        } finally {\n          try {\n            reader.releaseLock();\n          } catch {\n            // best-effort cleanup\n          }\n        }\n\n        res.type(\"text/plain\").send(Buffer.concat(chunks, bytesRead));\n      } catch (error) {\n        this._handleApiError(res, error, \"Read failed\");\n      }\n    });\n  }\n\n  private async _handleDownload(\n    req: express.Request,\n    res: express.Response,\n    connector: FilesConnector,\n    volumeKey: string,\n  ): Promise<void> {\n    return this._serveFile(req, res, connector, volumeKey, {\n      mode: \"download\",\n    });\n  }\n\n  private async _handleRaw(\n    req: express.Request,\n    res: express.Response,\n    connector: FilesConnector,\n    volumeKey: string,\n  ): Promise<void> {\n    return this._serveFile(req, res, connector, volumeKey, {\n      mode: \"raw\",\n    });\n  }\n\n  /**\n   * Shared handler for `/download` and `/raw` endpoints.\n   * - `download`: always forces `Content-Disposition: attachment`.\n   * - `raw`: adds CSP sandbox; forces attachment only for unsafe content types.\n   */\n  private async _serveFile(\n    req: express.Request,\n    res: express.Response,\n    connector: FilesConnector,\n    volumeKey: string,\n    opts: { mode: \"download\" | \"raw\" },\n  ): Promise<void> {\n    const query = this._readPathQuery(req, res);\n    if (!query) return;\n    const rawPath = query.path;\n\n    const valid = this._isValidPath(rawPath);\n    if (valid !== true) {\n      res.status(400).json({ error: valid, plugin: this.name });\n      return;\n    }\n    const path = rawPath as string;\n\n    if (!(await this._enforcePolicy(req, res, volumeKey, opts.mode, path)))\n      return;\n\n    const label = opts.mode === \"download\" ? \"Download\" : \"Raw fetch\";\n    const volumeCfg = this.volumeConfigs[volumeKey];\n    const { mode, userCtx } = this._resolveAuthForRequest(req, volumeKey);\n\n    await this._runWithAuth(userCtx, async () => {\n      try {\n        const settings = this._downloadSettings(mode);\n        const response = await this.execute(\n          async () => connector.download(getWorkspaceClient(), path),\n          settings,\n        );\n\n        if (!response.ok) {\n          this._sendStatusError(res, response.status);\n          return;\n        }\n\n        const resolvedType = contentTypeFromPath(\n          path,\n          undefined,\n          volumeCfg.customContentTypes,\n        );\n        const fileName = sanitizeFilename(path.split(\"/\").pop() ?? \"download\");\n\n        res.setHeader(\"Content-Type\", resolvedType);\n        res.setHeader(\"X-Content-Type-Options\", \"nosniff\");\n\n        if (opts.mode === \"raw\") {\n          res.setHeader(\"Content-Security-Policy\", \"sandbox\");\n          if (!isSafeInlineContentType(resolvedType)) {\n            res.setHeader(\n              \"Content-Disposition\",\n              `attachment; filename=\"${fileName}\"`,\n            );\n          }\n        } else {\n          res.setHeader(\n            \"Content-Disposition\",\n            `attachment; filename=\"${fileName}\"`,\n          );\n        }\n\n        if (response.data.contents) {\n          const nodeStream = Readable.fromWeb(\n            response.data.contents as import(\"node:stream/web\").ReadableStream,\n          );\n          nodeStream.on(\"error\", (err) => {\n            logger.error(\"Stream error during %s: %O\", opts.mode, err);\n            if (!res.headersSent) {\n              this._sendStatusError(res, 500);\n            } else {\n              res.destroy();\n            }\n          });\n          nodeStream.pipe(res);\n        } else {\n          res.end();\n        }\n      } catch (error) {\n        this._handleApiError(res, error, `${label} failed`);\n      }\n    });\n  }\n\n  private async _handleExists(\n    req: express.Request,\n    res: express.Response,\n    connector: FilesConnector,\n    volumeKey: string,\n  ): Promise<void> {\n    const query = this._readPathQuery(req, res);\n    if (!query) return;\n    const rawPath = query.path;\n\n    const valid = this._isValidPath(rawPath);\n    if (valid !== true) {\n      res.status(400).json({ error: valid, plugin: this.name });\n      return;\n    }\n    const path = rawPath as string;\n\n    if (!(await this._enforcePolicy(req, res, volumeKey, \"exists\", path)))\n      return;\n\n    const { mode, userCtx } = this._resolveAuthForRequest(req, volumeKey);\n    await this._runWithAuth(userCtx, async () => {\n      try {\n        const result = await this.execute(\n          async () => connector.exists(getWorkspaceClient(), path),\n          this._readSettings(\n            [`files:${volumeKey}:exists`, connector.resolvePath(path)],\n            mode,\n          ),\n        );\n\n        if (!result.ok) {\n          this._sendStatusError(res, result.status);\n          return;\n        }\n        res.json({ exists: result.data });\n      } catch (error) {\n        this._handleApiError(res, error, \"Exists check failed\");\n      }\n    });\n  }\n\n  private async _handleMetadata(\n    req: express.Request,\n    res: express.Response,\n    connector: FilesConnector,\n    volumeKey: string,\n  ): Promise<void> {\n    const query = this._readPathQuery(req, res);\n    if (!query) return;\n    const rawPath = query.path;\n\n    const valid = this._isValidPath(rawPath);\n    if (valid !== true) {\n      res.status(400).json({ error: valid, plugin: this.name });\n      return;\n    }\n    const path = rawPath as string;\n\n    if (!(await this._enforcePolicy(req, res, volumeKey, \"metadata\", path)))\n      return;\n\n    const { mode, userCtx } = this._resolveAuthForRequest(req, volumeKey);\n    await this._runWithAuth(userCtx, async () => {\n      try {\n        const result = await this.execute(\n          async () => connector.metadata(getWorkspaceClient(), path),\n          this._readSettings(\n            [`files:${volumeKey}:metadata`, connector.resolvePath(path)],\n            mode,\n          ),\n        );\n\n        if (!result.ok) {\n          this._sendStatusError(res, result.status);\n          return;\n        }\n        res.json(result.data);\n      } catch (error) {\n        this._handleApiError(res, error, \"Metadata fetch failed\");\n      }\n    });\n  }\n\n  private async _handlePreview(\n    req: express.Request,\n    res: express.Response,\n    connector: FilesConnector,\n    volumeKey: string,\n  ): Promise<void> {\n    const query = this._readPathQuery(req, res);\n    if (!query) return;\n    const rawPath = query.path;\n\n    const valid = this._isValidPath(rawPath);\n    if (valid !== true) {\n      res.status(400).json({ error: valid, plugin: this.name });\n      return;\n    }\n    const path = rawPath as string;\n\n    if (!(await this._enforcePolicy(req, res, volumeKey, \"preview\", path)))\n      return;\n\n    const { mode, userCtx } = this._resolveAuthForRequest(req, volumeKey);\n    await this._runWithAuth(userCtx, async () => {\n      try {\n        const result = await this.execute(\n          async () => connector.preview(getWorkspaceClient(), path),\n          this._readSettings(\n            [`files:${volumeKey}:preview`, connector.resolvePath(path)],\n            mode,\n          ),\n        );\n\n        if (!result.ok) {\n          this._sendStatusError(res, result.status);\n          return;\n        }\n        res.json(result.data);\n      } catch (error) {\n        this._handleApiError(res, error, \"Preview failed\");\n      }\n    });\n  }\n\n  private async _handleUpload(\n    req: express.Request,\n    res: express.Response,\n    connector: FilesConnector,\n    volumeKey: string,\n  ): Promise<void> {\n    const query = this._readPathQuery(req, res);\n    if (!query) return;\n    const rawPath = query.path;\n    const valid = this._isValidPath(rawPath);\n    if (valid !== true) {\n      res.status(400).json({ error: valid, plugin: this.name });\n      return;\n    }\n    const path = rawPath as string;\n\n    const volumeCfg = this.volumeConfigs[volumeKey];\n    const maxSize = volumeCfg.maxUploadSize ?? FILES_MAX_UPLOAD_SIZE;\n    const rawContentLength = req.headers[\"content-length\"];\n    let contentLength: number | undefined;\n\n    if (typeof rawContentLength === \"string\" && rawContentLength.length > 0) {\n      if (!/^\\d+$/.test(rawContentLength)) {\n        res.status(400).json({\n          error: \"Invalid Content-Length header.\",\n          plugin: this.name,\n        });\n        return;\n      }\n      contentLength = Number(rawContentLength);\n    }\n\n    if (\n      !(await this._enforcePolicy(req, res, volumeKey, \"upload\", path, {\n        size: contentLength,\n      }))\n    )\n      return;\n\n    if (contentLength !== undefined && contentLength > maxSize) {\n      res.status(413).json({\n        error: `File size (${contentLength} bytes) exceeds maximum allowed size (${maxSize} bytes).`,\n        plugin: this.name,\n      });\n      return;\n    }\n\n    logger.debug(req, \"Upload started: volume=%s path=%s\", volumeKey, path);\n\n    const { mode, userCtx } = this._resolveAuthForRequest(req, volumeKey);\n    await this._runWithAuth(userCtx, async () => {\n      try {\n        const rawStream: ReadableStream<Uint8Array> = Readable.toWeb(req);\n\n        let bytesReceived = 0;\n        const webStream = rawStream.pipeThrough(\n          new TransformStream<Uint8Array, Uint8Array>({\n            transform(chunk, controller) {\n              bytesReceived += chunk.byteLength;\n              if (bytesReceived > maxSize) {\n                controller.error(\n                  new Error(\n                    `Upload stream exceeds maximum allowed size (${maxSize} bytes)`,\n                  ),\n                );\n                return;\n              }\n              // When the client declared a Content-Length, the policy was\n              // gated on that value (lines above pass `size: contentLength`\n              // to `_enforcePolicy`). Refuse bytes beyond the declared size\n              // so an attacker cannot bypass a per-user policy by sending a\n              // small Content-Length and then streaming up to maxSize.\n              if (\n                contentLength !== undefined &&\n                bytesReceived > contentLength\n              ) {\n                controller.error(\n                  new Error(\n                    `Upload stream exceeds declared Content-Length (${contentLength} bytes)`,\n                  ),\n                );\n                return;\n              }\n              controller.enqueue(chunk);\n            },\n          }),\n        );\n\n        logger.debug(\n          req,\n          \"Upload body received: volume=%s path=%s, size=%d bytes\",\n          volumeKey,\n          path,\n          contentLength ?? 0,\n        );\n        const settings = this._writeSettings(mode);\n        // The connector's `upload` resolves `getWorkspaceClient()` and\n        // `client.config.authenticate(headers)` synchronously inside this\n        // callback. When `_runWithAuth` wraps us in `runInUserContext`, that\n        // chain produces user-token Authorization headers on the outgoing\n        // `fetch PUT`. The OBO upload-headers test pins this contract.\n        const result = await this.trackWrite(() =>\n          this.execute(async () => {\n            await connector.upload(getWorkspaceClient(), path, webStream);\n            return { success: true as const };\n          }, settings),\n        );\n\n        // Awaited before sending the response so that a follow-up\n        // `GET /list` issued in the same tick cannot race the\n        // underlying `cache.delete()` and observe pre-write data.\n        await this._invalidateListCache(volumeKey, path, connector, mode);\n\n        if (!result.ok) {\n          logger.error(\n            req,\n            \"Upload failed: volume=%s path=%s, size=%d bytes\",\n            volumeKey,\n            path,\n            contentLength ?? 0,\n          );\n          this._sendStatusError(res, result.status);\n          return;\n        }\n\n        logger.debug(\n          req,\n          \"Upload complete: volume=%s path=%s\",\n          volumeKey,\n          path,\n        );\n        res.json(result.data);\n      } catch (error) {\n        if (\n          error instanceof Error &&\n          (error.message.includes(\"exceeds maximum allowed size\") ||\n            error.message.includes(\"exceeds declared Content-Length\"))\n        ) {\n          res.status(413).json({ error: error.message, plugin: this.name });\n          return;\n        }\n        this._handleApiError(res, error, \"Upload failed\");\n      }\n    });\n  }\n\n  private async _handleMkdir(\n    req: express.Request,\n    res: express.Response,\n    connector: FilesConnector,\n    volumeKey: string,\n  ): Promise<void> {\n    const dirPath =\n      typeof req.body?.path === \"string\" ? req.body.path : undefined;\n\n    const valid = this._isValidPath(dirPath);\n    if (valid !== true) {\n      res.status(400).json({ error: valid, plugin: this.name });\n      return;\n    }\n\n    if (!(await this._enforcePolicy(req, res, volumeKey, \"mkdir\", dirPath)))\n      return;\n\n    const { mode, userCtx } = this._resolveAuthForRequest(req, volumeKey);\n    await this._runWithAuth(userCtx, async () => {\n      try {\n        const settings = this._writeSettings(mode);\n        const result = await this.trackWrite(() =>\n          this.execute(async () => {\n            await connector.createDirectory(getWorkspaceClient(), dirPath);\n            return { success: true as const };\n          }, settings),\n        );\n\n        // Awaited before sending the response so that a follow-up\n        // `GET /list` issued in the same tick cannot race the\n        // underlying `cache.delete()` and observe pre-write data.\n        await this._invalidateListCache(volumeKey, dirPath, connector, mode);\n\n        if (!result.ok) {\n          this._sendStatusError(res, result.status);\n          return;\n        }\n\n        res.json(result.data);\n      } catch (error) {\n        this._handleApiError(res, error, \"Create directory failed\");\n      }\n    });\n  }\n\n  private async _handleDelete(\n    req: express.Request,\n    res: express.Response,\n    connector: FilesConnector,\n    volumeKey: string,\n  ): Promise<void> {\n    const query = this._readPathQuery(req, res);\n    if (!query) return;\n    const rawPath = query.path;\n\n    const valid = this._isValidPath(rawPath);\n    if (valid !== true) {\n      res.status(400).json({ error: valid, plugin: this.name });\n      return;\n    }\n    const path = rawPath as string;\n\n    if (!(await this._enforcePolicy(req, res, volumeKey, \"delete\", path)))\n      return;\n\n    const { mode, userCtx } = this._resolveAuthForRequest(req, volumeKey);\n    await this._runWithAuth(userCtx, async () => {\n      try {\n        const settings = this._writeSettings(mode);\n        const result = await this.trackWrite(() =>\n          this.execute(async () => {\n            await connector.delete(getWorkspaceClient(), path);\n            return { success: true as const };\n          }, settings),\n        );\n\n        // Awaited before sending the response so that a follow-up\n        // `GET /list` issued in the same tick cannot race the\n        // underlying `cache.delete()` and observe pre-write data.\n        await this._invalidateListCache(volumeKey, path, connector, mode);\n\n        if (!result.ok) {\n          this._sendStatusError(res, result.status);\n          return;\n        }\n\n        res.json(result.data);\n      } catch (error) {\n        this._handleApiError(res, error, \"Delete failed\");\n      }\n    });\n  }\n\n  private _resolveAuth(\n    volumeKey: string,\n  ): \"service-principal\" | \"on-behalf-of-user\" {\n    return (\n      this.volumeConfigs[volumeKey]?.auth ??\n      this.config.auth ??\n      \"service-principal\"\n    );\n  }\n\n  /**\n   * Build a `UserContext` from request headers when both\n   * `x-forwarded-access-token` and `x-forwarded-user` are present, otherwise\n   * return `null`. Used by OBO route handlers to wrap SDK calls in the\n   * end-user's identity. A `null` result means \"fall back to the service\n   * principal client\" — for OBO volumes in production, `_enforcePolicy` will\n   * already have responded 401 before we get here, so `null` is reachable\n   * only on the dev-fallback path.\n   */\n  private _buildUserContextOrNull(req: express.Request): UserContext | null {\n    const token = req.header(\"x-forwarded-access-token\")?.trim();\n    const userId = req.header(\"x-forwarded-user\")?.trim();\n    if (!token || !userId) return null;\n    return ServiceContext.createUserContext(token, userId);\n  }\n\n  /**\n   * Build the telemetry attribute hash for the `files.auth_mode` span\n   * attribute. The value reflects what operationally happened — i.e.\n   * whether `runInUserContext` actually wrapped the SDK call:\n   * - HTTP route on OBO volume + valid token → `\"on-behalf-of-user\"`.\n   * - HTTP route on OBO volume + dev-fallback (no token) →\n   *   `\"service-principal\"` (the route falls through to the SP client).\n   * - HTTP route on SP volume → `\"service-principal\"`.\n   * - `asUser(req)` programmatic calls with a real user context →\n   *   `\"on-behalf-of-user\"`.\n   * - Any unwrapped path → `\"service-principal\"`.\n   */\n  private _authModeAttributes(\n    authMode: \"service-principal\" | \"on-behalf-of-user\",\n  ): { \"files.auth_mode\": string } {\n    return { \"files.auth_mode\": authMode };\n  }\n\n  /**\n   * One-shot resolver for HTTP route handlers. Builds the request's\n   * `UserContext` AT MOST ONCE (when the volume is OBO and the headers are\n   * present) and returns both the operationally-effective auth mode and the\n   * pre-built `UserContext`.\n   *\n   * Handlers thread the `userCtx` into `_runWithAuth(userCtx, fn)` to avoid\n   * a second `ServiceContext.createUserContext()` allocation — that call\n   * builds a fresh `WorkspaceClient` per invocation, so doing it twice per\n   * request was pure throwaway overhead.\n   */\n  private _resolveAuthForRequest(\n    req: express.Request,\n    volumeKey: string,\n  ): {\n    mode: \"service-principal\" | \"on-behalf-of-user\";\n    userCtx: UserContext | null;\n  } {\n    if (this._resolveAuth(volumeKey) !== \"on-behalf-of-user\") {\n      return { mode: \"service-principal\", userCtx: null };\n    }\n    const userCtx = this._buildUserContextOrNull(req);\n    return userCtx\n      ? { mode: \"on-behalf-of-user\", userCtx }\n      : { mode: \"service-principal\", userCtx: null };\n  }\n\n  /**\n   * Run `fn` under the correct execution context.\n   * - `userCtx` is `null`: invokes `fn` directly so the service-principal\n   *   `WorkspaceClient` and `getCurrentUserId()` are used — identical\n   *   behavior to pre-OBO releases. This covers both SP volumes and the\n   *   OBO dev-fallback path (where headers were missing).\n   * - `userCtx` is a `UserContext`: wraps `fn` in `runInUserContext(userCtx)`,\n   *   so SDK calls execute as the end user and `getCurrentUserId()` (and\n   *   therefore cache keys) resolve to the user's ID.\n   *\n   * The caller is responsible for building `userCtx` exactly once per\n   * request via `_resolveAuthForRequest`; this signature deliberately does\n   * NOT take a `req` so it cannot accidentally re-build the context.\n   */\n  private async _runWithAuth(\n    userCtx: UserContext | null,\n    fn: () => Promise<void>,\n  ): Promise<void> {\n    if (userCtx) {\n      return runInUserContext(userCtx, fn);\n    }\n    return fn();\n  }\n\n  /**\n   * Tag the span that `FilesConnector.<operation>` opens with\n   * `files.auth_mode`. Programmatic VolumeAPI methods bypass\n   * `this.execute(...)` (and therefore the `TelemetryInterceptor`), so the\n   * connector's own `files.<operation>` span is the natural place to land\n   * this attribute. Rather than opening a parent `files.<operation>` span\n   * (which would duplicate the connector's span — same name, doubled\n   * allocation/export), we propagate the attribute via AsyncLocalStorage\n   * and let the connector merge it into its existing span at creation\n   * time.\n   *\n   * The `operation` parameter is unused by the propagation mechanism (the\n   * connector knows its own operation), but kept in the signature for API\n   * stability with the previous span-creation form.\n   */\n  private _withAuthModeAttributes<R>(\n    _operation: string,\n    authMode: \"service-principal\" | \"on-behalf-of-user\",\n    fn: () => Promise<R>,\n  ): Promise<R> {\n    return runWithFilesSpanAttributes(this._authModeAttributes(authMode), fn);\n  }\n\n  /**\n   * Wrap each `VolumeAPI` method so the `FilesConnector` span it produces is\n   * tagged with `files.auth_mode = \"service-principal\"`. Used for\n   * programmatic calls that don't go through `asUser(req)`.\n   *\n   * The attribute is attached to the connector's existing span via\n   * AsyncLocalStorage propagation (see `_withAuthModeAttributes`); no\n   * additional parent span is opened, so each call produces exactly one\n   * `files.<operation>` span instead of two.\n   */\n  private _wrapVolumeAPIWithSPSpan(api: VolumeAPI): VolumeAPI {\n    const wrap =\n      <Args extends unknown[], R>(\n        operation: string,\n        fn: (...args: Args) => Promise<R>,\n      ): ((...args: Args) => Promise<R>) =>\n      (...args: Args) =>\n        this._withAuthModeAttributes(operation, \"service-principal\", () =>\n          fn(...args),\n        );\n\n    return {\n      list: wrap(\"list\", api.list),\n      read: wrap(\"read\", api.read),\n      download: wrap(\"download\", api.download),\n      exists: wrap(\"exists\", api.exists),\n      metadata: wrap(\"metadata\", api.metadata),\n      upload: wrap(\"upload\", api.upload),\n      createDirectory: wrap(\"createDirectory\", api.createDirectory),\n      delete: wrap(\"delete\", api.delete),\n      preview: wrap(\"preview\", api.preview),\n    };\n  }\n\n  /**\n   * Wrap each `VolumeAPI` method so its execution runs inside\n   * `runInUserContext(userCtx, ...)`. Used by `VolumeHandle.asUser(req)` to\n   * force the SDK identity to the end user regardless of the volume's\n   * `auth` setting. The policy check baked into each method (via\n   * `createVolumeAPI`) runs inside the same scope, so `getCurrentUserId()`\n   * and any cache `userKey` derived from it also resolve to the user.\n   *\n   * Each wrapped invocation tags the connector's span with\n   * `files.auth_mode = \"on-behalf-of-user\"` via AsyncLocalStorage\n   * propagation — no additional parent span is opened.\n   */\n  private _wrapVolumeAPIInUserContext(\n    api: VolumeAPI,\n    userCtx: UserContext,\n  ): VolumeAPI {\n    const wrap =\n      <Args extends unknown[], R>(\n        operation: string,\n        fn: (...args: Args) => Promise<R>,\n      ): ((...args: Args) => Promise<R>) =>\n      (...args: Args) =>\n        this._withAuthModeAttributes(operation, \"on-behalf-of-user\", () =>\n          runInUserContext(userCtx, () => fn(...args)),\n        );\n\n    return {\n      list: wrap(\"list\", api.list),\n      read: wrap(\"read\", api.read),\n      download: wrap(\"download\", api.download),\n      exists: wrap(\"exists\", api.exists),\n      metadata: wrap(\"metadata\", api.metadata),\n      upload: wrap(\"upload\", api.upload),\n      createDirectory: wrap(\"createDirectory\", api.createDirectory),\n      delete: wrap(\"delete\", api.delete),\n      preview: wrap(\"preview\", api.preview),\n    };\n  }\n\n  /**\n   * Creates a VolumeAPI for a specific volume key.\n   *\n   * Enforces the volume's policy before each operation.\n   */\n  protected createVolumeAPI(\n    volumeKey: string,\n    user: FilePolicyUser,\n  ): VolumeAPI {\n    const connector = this.volumeConnectors[volumeKey];\n    const check = (\n      action: FileAction,\n      path: string,\n      overrides?: Partial<FileResource>,\n    ) => this._checkPolicy(volumeKey, action, path, user, overrides);\n\n    return {\n      list: async (directoryPath?: string) => {\n        await check(\"list\", directoryPath ?? \"/\");\n        return connector.list(getWorkspaceClient(), directoryPath);\n      },\n      read: async (filePath: string, opts?: { maxSize?: number }) => {\n        await check(\"read\", filePath);\n        return connector.read(getWorkspaceClient(), filePath, opts);\n      },\n      download: async (filePath: string) => {\n        await check(\"download\", filePath);\n        return connector.download(getWorkspaceClient(), filePath);\n      },\n      exists: async (filePath: string) => {\n        await check(\"exists\", filePath);\n        return connector.exists(getWorkspaceClient(), filePath);\n      },\n      metadata: async (filePath: string) => {\n        await check(\"metadata\", filePath);\n        return connector.metadata(getWorkspaceClient(), filePath);\n      },\n      upload: async (\n        filePath: string,\n        contents: ReadableStream | Buffer | string,\n        opts?: { overwrite?: boolean },\n      ) => {\n        await check(\"upload\", filePath);\n        return connector.upload(getWorkspaceClient(), filePath, contents, opts);\n      },\n      createDirectory: async (directoryPath: string) => {\n        await check(\"mkdir\", directoryPath);\n        return connector.createDirectory(getWorkspaceClient(), directoryPath);\n      },\n      delete: async (filePath: string) => {\n        await check(\"delete\", filePath);\n        return connector.delete(getWorkspaceClient(), filePath);\n      },\n      preview: async (filePath: string) => {\n        await check(\"preview\", filePath);\n        return connector.preview(getWorkspaceClient(), filePath);\n      },\n    };\n  }\n\n  /**\n   * Builds the agent-tool registry entries for a single volume. One set of\n   * tools per configured volume, keyed by `${volumeKey}.${method}`.\n   *\n   * Each handler resolves the caller's identity from the current execution\n   * context (OBO user when the agent run is wrapped in `asUser(req)`, service\n   * principal otherwise in local dev) and dispatches through\n   * `createVolumeAPI(volumeKey, user)` so the volume's policy is enforced\n   * uniformly for agent and HTTP callers.\n   */\n  private _defineVolumeTools(volumeKey: string): ToolRegistry {\n    const buildUser = (): FilePolicyUser => {\n      const ctx = getExecutionContext();\n      return isUserContext(ctx)\n        ? { id: ctx.userId }\n        : { id: ctx.serviceUserId, isServicePrincipal: true };\n    };\n    const api = () => this.createVolumeAPI(volumeKey, buildUser());\n    return {\n      [`${volumeKey}.list`]: defineTool({\n        description: `List files and directories in the \"${volumeKey}\" volume`,\n        schema: z.object({\n          path: z\n            .string()\n            .optional()\n            .describe(\"Directory path to list (optional, defaults to root)\"),\n        }),\n        annotations: { effect: \"read\", requiresUserContext: true },\n        autoInheritable: true,\n        execute: (args, signal) => {\n          signal?.throwIfAborted();\n          return api().list(args.path);\n        },\n      }),\n      [`${volumeKey}.read`]: defineTool({\n        description: `Read a text file from the \"${volumeKey}\" volume`,\n        schema: z.object({\n          path: z.string().describe(\"File path to read\"),\n        }),\n        annotations: { effect: \"read\", requiresUserContext: true },\n        autoInheritable: true,\n        execute: (args, signal) => {\n          signal?.throwIfAborted();\n          return api().read(args.path);\n        },\n      }),\n      [`${volumeKey}.exists`]: defineTool({\n        description: `Check if a file or directory exists in the \"${volumeKey}\" volume`,\n        schema: z.object({\n          path: z.string().describe(\"Path to check\"),\n        }),\n        annotations: { effect: \"read\", requiresUserContext: true },\n        autoInheritable: true,\n        execute: (args, signal) => {\n          signal?.throwIfAborted();\n          return api().exists(args.path);\n        },\n      }),\n      [`${volumeKey}.metadata`]: defineTool({\n        description: `Get metadata (size, type, last modified) for a file in the \"${volumeKey}\" volume`,\n        schema: z.object({\n          path: z.string().describe(\"File path\"),\n        }),\n        annotations: { effect: \"read\", requiresUserContext: true },\n        autoInheritable: true,\n        execute: (args, signal) => {\n          signal?.throwIfAborted();\n          return api().metadata(args.path);\n        },\n      }),\n      [`${volumeKey}.upload`]: defineTool({\n        description: `Upload a text file to the \"${volumeKey}\" volume`,\n        schema: z.object({\n          path: z.string().describe(\"Destination file path\"),\n          contents: z.string().describe(\"File contents as a string\"),\n          overwrite: z\n            .boolean()\n            .optional()\n            .describe(\"Whether to overwrite existing file\"),\n        }),\n        annotations: { effect: \"destructive\", requiresUserContext: true },\n        execute: (args, signal) => {\n          signal?.throwIfAborted();\n          return api().upload(args.path, args.contents, {\n            overwrite: args.overwrite,\n          });\n        },\n      }),\n      [`${volumeKey}.delete`]: defineTool({\n        description: `Delete a file from the \"${volumeKey}\" volume`,\n        schema: z.object({\n          path: z.string().describe(\"File path to delete\"),\n        }),\n        annotations: { effect: \"destructive\", requiresUserContext: true },\n        execute: (args, signal) => {\n          signal?.throwIfAborted();\n          return api().delete(args.path);\n        },\n      }),\n    };\n  }\n\n  private inflightWrites = 0;\n\n  private trackWrite<T>(fn: () => Promise<T>): Promise<T> {\n    this.inflightWrites++;\n    return fn().finally(() => {\n      this.inflightWrites--;\n    });\n  }\n\n  async shutdown(): Promise<void> {\n    // Wait up to 10 seconds for in-flight write operations to finish\n    const deadline = Date.now() + 10_000;\n    while (this.inflightWrites > 0 && Date.now() < deadline) {\n      logger.info(\n        \"Waiting for %d in-flight write(s) to complete before shutdown…\",\n        this.inflightWrites,\n      );\n      await new Promise((resolve) => setTimeout(resolve, 500));\n    }\n    if (this.inflightWrites > 0) {\n      logger.warn(\n        \"Shutdown deadline reached with %d in-flight write(s) still pending.\",\n        this.inflightWrites,\n      );\n    }\n    this.streamManager.abortAll();\n  }\n\n  getAgentTools(): AgentToolDefinition[] {\n    return toolsFromRegistry(this.tools);\n  }\n\n  async executeAgentTool(\n    name: string,\n    args: unknown,\n    signal?: AbortSignal,\n  ): Promise<unknown> {\n    return executeFromRegistry(this.tools, name, args, signal);\n  }\n\n  toolkit(opts?: import(\"../../core/agent/types\").ToolkitOptions) {\n    return buildToolkitEntries(this.name, this.tools, opts);\n  }\n\n  /**\n   * Returns the programmatic API for the Files plugin.\n   * Callable with a volume key to get a volume-scoped handle.\n   *\n   * SP volumes (`auth: \"service-principal\"`, the default) execute as the\n   * service principal. OBO volumes (`auth: \"on-behalf-of-user\"`) executed\n   * through the HTTP routes run as the end user; for programmatic calls\n   * outside a route, use `asUser(req)` to opt into per-user execution.\n   * `asUser(req)` is a hard override at the SDK level: it forces every\n   * subsequent call to execute as the end user inside `runInUserContext`,\n   * regardless of the volume's `auth` setting. Policies control per-user\n   * access in either mode.\n   *\n   * @example\n   * ```ts\n   * // Service principal access\n   * appKit.files(\"uploads\").list()\n   *\n   * // With policy: pass user identity for access control. The SDK call\n   * // also executes as the user (not the service principal).\n   * appKit.files(\"uploads\").asUser(req).list()\n   * ```\n   */\n  exports(): FilesExport {\n    const resolveVolume = (volumeKey: string): VolumeHandle => {\n      if (!this.volumeKeys.includes(volumeKey)) {\n        throw new Error(\n          `Unknown volume \"${volumeKey}\". Available volumes: ${this.volumeKeys.join(\", \")}`,\n        );\n      }\n\n      // Lazy user resolution: getCurrentUserId() is called when a method\n      // is invoked (policy check), not when exports() is called.\n      const spUser: FilePolicyUser = {\n        get id() {\n          return getCurrentUserId();\n        },\n        isServicePrincipal: true,\n      };\n      // Default (non-asUser) programmatic surface: every call is tagged\n      // with `files.auth_mode = \"service-principal\"` for telemetry parity\n      // with the HTTP route path.\n      const spApi = this._wrapVolumeAPIWithSPSpan(\n        this.createVolumeAPI(volumeKey, spUser),\n      );\n\n      return {\n        ...spApi,\n        asUser: (req: express.Request) => {\n          const user = this._extractUser(req);\n          const api = this.createVolumeAPI(volumeKey, user);\n          // Force OBO at the SDK level regardless of the volume's `auth`\n          // setting: each method runs inside `runInUserContext` so\n          // `getWorkspaceClient()` returns the user-token client. When no\n          // user token is available (only reachable in dev mode after the\n          // strict `_extractUser` falls back to the SP identity), we skip\n          // the OBO wrap and instead apply the SP-mode span wrap so trace\n          // output reflects the actual SP execution.\n          const userCtx = this._buildUserContextOrNull(req);\n          if (!userCtx) return this._wrapVolumeAPIWithSPSpan(api);\n          return this._wrapVolumeAPIInUserContext(api, userCtx);\n        },\n      };\n    };\n\n    const filesExport = ((volumeKey: string) =>\n      resolveVolume(volumeKey)) as FilesExport;\n    filesExport.volume = resolveVolume;\n\n    return filesExport;\n  }\n\n  clientConfig(): Record<string, unknown> {\n    return { volumes: this.volumeKeys };\n  }\n}\n\n/**\n * @internal\n */\nexport const files = Object.assign(toPlugin(FilesPlugin), { policy });\n"],"mappings":"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"}

package/dist/plugins/files/policy.d.ts

@@ -23,8 +23,37 @@ interface FileResource {
 }
 /** Minimal user identity passed to the policy function. */
 interface FilePolicyUser {
+  /**
+   * Identifier of the requesting caller. For end-user HTTP requests this is
+   * the value of the `x-forwarded-user` header; for direct SDK calls and
+   * header-less HTTP requests (which run as the service principal), this is
+   * the service principal's ID.
+   */
   id: string;
-  /** `true` when the caller is the service principal (direct SDK call, not `asUser`). */
+  /**
+   * `true` when the call is executing as the service principal — either a
+   * direct SDK call (`appKit.files(...)`) or an HTTP request that arrived
+   * without an `x-forwarded-user` / `x-forwarded-access-token` header.
+   * Policy authors typically check this first to distinguish SP traffic
+   * from end-user traffic.
+   *
+   * The flag reflects the **policy user** the plugin selects, which
+   * combines the volume's effective `auth` mode with the headers on the
+   * incoming request. The full matrix:
+   *
+   * | Volume `auth`         | Path                           | Headers                       | `isServicePrincipal` | Notes                                                                                          |
+   * | --------------------- | ------------------------------ | ----------------------------- | -------------------- | ---------------------------------------------------------------------------------------------- |
+   * | `service-principal`   | HTTP                           | `x-forwarded-user` present    | `false` (or unset)   | Pre-OBO behavior. Policy sees the end user but the SDK call still runs as the SP.              |
+   * | `service-principal`   | HTTP                           | no `x-forwarded-user`         | `true`               | Headerless request — policy and SDK both run as the SP.                                        |
+   * | `on-behalf-of-user`   | HTTP                           | valid token + user header     | `false`              | Real end-user execution. Policy sees the user; the SDK call also runs as the user.             |
+   * | `on-behalf-of-user`   | HTTP                           | missing token, dev-fallback   | `true`               | Only reachable when `NODE_ENV === "development"` (prod returns 401). Treated as SP traffic.    |
+   * | any                   | Programmatic `asUser(req)`     | `x-forwarded-user` present    | `false`              | `asUser` extracts the user; the SDK call runs as the user inside `runInUserContext`.           |
+   *
+   * Programmatic calls without `asUser(req)` always set
+   * `isServicePrincipal: true` because no request is available to derive a
+   * user identity from. OBO volume defaults apply only to HTTP route
+   * traffic; for programmatic per-user execution, use `asUser(req)`.
+   */
   isServicePrincipal?: boolean;
 }
 /**

package/dist/plugins/files/policy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"policy.d.ts","names":[],"sources":["../../../src/plugins/files/policy.ts"],"mappings":";;AAaA;;;;;AAaA;;KAbY,UAAA;;cAaC,YAAA,EAAc,WAAA,CAAY,UAAA;AAWvC;AAAA,cAAa,aAAA,EAAe,WAAA,CAAY,UAAA;;UAWvB,YAAA;EAXiC;EAahD,IAAA;EAF2B;EAI3B,MAAA;EAJ2B;EAM3B,IAAA;AAAA;;UAIe,cAAA;EACf,EAAA;EADe;EAGf,kBAAA;AAAA;;;AAWF;;KAAY,UAAA,IACV,MAAA,EAAQ,UAAA,EACR,QAAA,EAAU,YAAA,EACV,IAAA,EAAM,cAAA,eACO,OAAA;;;;cASF,iBAAA,SAA0B,KAAA;EAAA,SAC5B,MAAA,EAAQ,UAAA;EAAA,SACR,SAAA;cAEG,MAAA,EAAQ,UAAA,EAAY,SAAA;AAAA"}
+{"version":3,"file":"policy.d.ts","names":[],"sources":["../../../src/plugins/files/policy.ts"],"mappings":";;AAaA;;;;;AAaA;;KAbY,UAAA;;cAaC,YAAA,EAAc,WAAA,CAAY,UAAA;AAWvC;AAAA,cAAa,aAAA,EAAe,WAAA,CAAY,UAAA;;UAWvB,YAAA;EAXiC;EAahD,IAAA;EAF2B;EAI3B,MAAA;EAJ2B;EAM3B,IAAA;AAAA;;UAIe,cAAA;EAJX;AAIN;;;;;EAOE,EAAA;EAoCoB;;;;;;;;;;;;;;;;;AAatB;;;;;;;EAxBE,kBAAA;AAAA;;;;;KAWU,UAAA,IACV,MAAA,EAAQ,UAAA,EACR,QAAA,EAAU,YAAA,EACV,IAAA,EAAM,cAAA,eACO,OAAA;;;;cASF,iBAAA,SAA0B,KAAA;EAAA,SAC5B,MAAA,EAAQ,UAAA;EAAA,SACR,SAAA;cAEG,MAAA,EAAQ,UAAA,EAAY,SAAA;AAAA"}

package/dist/plugins/files/policy.js.map

@@ -1 +1 @@
-{"version":3,"file":"policy.js","names":[],"sources":["../../../src/plugins/files/policy.ts"],"sourcesContent":["/**\n * Per-volume file access policies.\n *\n * A `FilePolicy` is a function that decides whether a given action on a\n * resource is allowed for a specific user. When a policy is attached to a\n * volume, the policy controls whether the action is allowed for the requesting user.\n */\n\n// ---------------------------------------------------------------------------\n// Actions\n// ---------------------------------------------------------------------------\n\n/** Every action the files plugin can perform. */\nexport type FileAction =\n  | \"list\"\n  | \"read\"\n  | \"download\"\n  | \"raw\"\n  | \"exists\"\n  | \"metadata\"\n  | \"preview\"\n  | \"upload\"\n  | \"mkdir\"\n  | \"delete\";\n\n/** Actions that only read data. */\nexport const READ_ACTIONS: ReadonlySet<FileAction> = new Set<FileAction>([\n  \"list\",\n  \"read\",\n  \"download\",\n  \"raw\",\n  \"exists\",\n  \"metadata\",\n  \"preview\",\n]);\n\n/** Actions that mutate data. */\nexport const WRITE_ACTIONS: ReadonlySet<FileAction> = new Set<FileAction>([\n  \"upload\",\n  \"mkdir\",\n  \"delete\",\n]);\n\n// ---------------------------------------------------------------------------\n// Resource & User\n// ---------------------------------------------------------------------------\n\n/** Describes the file or directory being acted upon. */\nexport interface FileResource {\n  /** Relative path within the volume. */\n  path: string;\n  /** The volume key (e.g. `\"uploads\"`). */\n  volume: string;\n  /** Content length in bytes — only present for uploads. */\n  size?: number;\n}\n\n/** Minimal user identity passed to the policy function. */\nexport interface FilePolicyUser {\n  id: string;\n  /** `true` when the caller is the service principal (direct SDK call, not `asUser`). */\n  isServicePrincipal?: boolean;\n}\n\n// ---------------------------------------------------------------------------\n// Policy function type\n// ---------------------------------------------------------------------------\n\n/**\n * A policy function that decides whether `user` may perform `action` on\n * `resource`. Return `true` to allow, `false` to deny.\n */\nexport type FilePolicy = (\n  action: FileAction,\n  resource: FileResource,\n  user: FilePolicyUser,\n) => boolean | Promise<boolean>;\n\n// ---------------------------------------------------------------------------\n// PolicyDeniedError\n// ---------------------------------------------------------------------------\n\n/**\n * Thrown when a policy denies an action.\n */\nexport class PolicyDeniedError extends Error {\n  readonly action: FileAction;\n  readonly volumeKey: string;\n\n  constructor(action: FileAction, volumeKey: string) {\n    super(`Policy denied \"${action}\" on volume \"${volumeKey}\"`);\n    this.name = \"PolicyDeniedError\";\n    this.action = action;\n    this.volumeKey = volumeKey;\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Combinators\n// ---------------------------------------------------------------------------\n\n/** Utility namespace with common policy combinators. */\nexport const policy = {\n  /**\n   * AND — all policies must allow. Short-circuits on first denial.\n   */\n  all(...policies: FilePolicy[]): FilePolicy {\n    if (policies.length === 0) {\n      throw new Error(\"policy.all() requires at least one policy\");\n    }\n    return async (action, resource, user) => {\n      for (const p of policies) {\n        if (!(await p(action, resource, user))) return false;\n      }\n      return true;\n    };\n  },\n\n  /**\n   * OR — at least one policy must allow. Short-circuits on first allow.\n   */\n  any(...policies: FilePolicy[]): FilePolicy {\n    if (policies.length === 0) {\n      throw new Error(\"policy.any() requires at least one policy\");\n    }\n    return async (action, resource, user) => {\n      for (const p of policies) {\n        if (await p(action, resource, user)) return true;\n      }\n      return false;\n    };\n  },\n\n  /** Negates a policy. */\n  not(p: FilePolicy): FilePolicy {\n    return async (action, resource, user) => !(await p(action, resource, user));\n  },\n\n  /** Allow all read actions (list, read, download, raw, exists, metadata, preview). */\n  publicRead(): FilePolicy {\n    return (action) => READ_ACTIONS.has(action);\n  },\n\n  /** Deny every action. */\n  denyAll(): FilePolicy {\n    return () => false;\n  },\n\n  /** Allow every action. */\n  allowAll(): FilePolicy {\n    return () => true;\n  },\n} as const;\n"],"mappings":";;AA0BA,MAAa,eAAwC,IAAI,IAAgB;CACvE;CACA;CACA;CACA;CACA;CACA;CACA;CACD,CAAC;;AAGF,MAAa,gBAAyC,IAAI,IAAgB;CACxE;CACA;CACA;CACD,CAAC;;;;AA4CF,IAAa,oBAAb,cAAuC,MAAM;CAC3C,AAAS;CACT,AAAS;CAET,YAAY,QAAoB,WAAmB;AACjD,QAAM,kBAAkB,OAAO,eAAe,UAAU,GAAG;AAC3D,OAAK,OAAO;AACZ,OAAK,SAAS;AACd,OAAK,YAAY;;;;AASrB,MAAa,SAAS;CAIpB,IAAI,GAAG,UAAoC;AACzC,MAAI,SAAS,WAAW,EACtB,OAAM,IAAI,MAAM,4CAA4C;AAE9D,SAAO,OAAO,QAAQ,UAAU,SAAS;AACvC,QAAK,MAAM,KAAK,SACd,KAAI,CAAE,MAAM,EAAE,QAAQ,UAAU,KAAK,CAAG,QAAO;AAEjD,UAAO;;;CAOX,IAAI,GAAG,UAAoC;AACzC,MAAI,SAAS,WAAW,EACtB,OAAM,IAAI,MAAM,4CAA4C;AAE9D,SAAO,OAAO,QAAQ,UAAU,SAAS;AACvC,QAAK,MAAM,KAAK,SACd,KAAI,MAAM,EAAE,QAAQ,UAAU,KAAK,CAAE,QAAO;AAE9C,UAAO;;;CAKX,IAAI,GAA2B;AAC7B,SAAO,OAAO,QAAQ,UAAU,SAAS,CAAE,MAAM,EAAE,QAAQ,UAAU,KAAK;;CAI5E,aAAyB;AACvB,UAAQ,WAAW,aAAa,IAAI,OAAO;;CAI7C,UAAsB;AACpB,eAAa;;CAIf,WAAuB;AACrB,eAAa;;CAEhB"}
+{"version":3,"file":"policy.js","names":[],"sources":["../../../src/plugins/files/policy.ts"],"sourcesContent":["/**\n * Per-volume file access policies.\n *\n * A `FilePolicy` is a function that decides whether a given action on a\n * resource is allowed for a specific user. When a policy is attached to a\n * volume, the policy controls whether the action is allowed for the requesting user.\n */\n\n// ---------------------------------------------------------------------------\n// Actions\n// ---------------------------------------------------------------------------\n\n/** Every action the files plugin can perform. */\nexport type FileAction =\n  | \"list\"\n  | \"read\"\n  | \"download\"\n  | \"raw\"\n  | \"exists\"\n  | \"metadata\"\n  | \"preview\"\n  | \"upload\"\n  | \"mkdir\"\n  | \"delete\";\n\n/** Actions that only read data. */\nexport const READ_ACTIONS: ReadonlySet<FileAction> = new Set<FileAction>([\n  \"list\",\n  \"read\",\n  \"download\",\n  \"raw\",\n  \"exists\",\n  \"metadata\",\n  \"preview\",\n]);\n\n/** Actions that mutate data. */\nexport const WRITE_ACTIONS: ReadonlySet<FileAction> = new Set<FileAction>([\n  \"upload\",\n  \"mkdir\",\n  \"delete\",\n]);\n\n// ---------------------------------------------------------------------------\n// Resource & User\n// ---------------------------------------------------------------------------\n\n/** Describes the file or directory being acted upon. */\nexport interface FileResource {\n  /** Relative path within the volume. */\n  path: string;\n  /** The volume key (e.g. `\"uploads\"`). */\n  volume: string;\n  /** Content length in bytes — only present for uploads. */\n  size?: number;\n}\n\n/** Minimal user identity passed to the policy function. */\nexport interface FilePolicyUser {\n  /**\n   * Identifier of the requesting caller. For end-user HTTP requests this is\n   * the value of the `x-forwarded-user` header; for direct SDK calls and\n   * header-less HTTP requests (which run as the service principal), this is\n   * the service principal's ID.\n   */\n  id: string;\n  /**\n   * `true` when the call is executing as the service principal — either a\n   * direct SDK call (`appKit.files(...)`) or an HTTP request that arrived\n   * without an `x-forwarded-user` / `x-forwarded-access-token` header.\n   * Policy authors typically check this first to distinguish SP traffic\n   * from end-user traffic.\n   *\n   * The flag reflects the **policy user** the plugin selects, which\n   * combines the volume's effective `auth` mode with the headers on the\n   * incoming request. The full matrix:\n   *\n   * | Volume `auth`         | Path                           | Headers                       | `isServicePrincipal` | Notes                                                                                          |\n   * | --------------------- | ------------------------------ | ----------------------------- | -------------------- | ---------------------------------------------------------------------------------------------- |\n   * | `service-principal`   | HTTP                           | `x-forwarded-user` present    | `false` (or unset)   | Pre-OBO behavior. Policy sees the end user but the SDK call still runs as the SP.              |\n   * | `service-principal`   | HTTP                           | no `x-forwarded-user`         | `true`               | Headerless request — policy and SDK both run as the SP.                                        |\n   * | `on-behalf-of-user`   | HTTP                           | valid token + user header     | `false`              | Real end-user execution. Policy sees the user; the SDK call also runs as the user.             |\n   * | `on-behalf-of-user`   | HTTP                           | missing token, dev-fallback   | `true`               | Only reachable when `NODE_ENV === \"development\"` (prod returns 401). Treated as SP traffic.    |\n   * | any                   | Programmatic `asUser(req)`     | `x-forwarded-user` present    | `false`              | `asUser` extracts the user; the SDK call runs as the user inside `runInUserContext`.           |\n   *\n   * Programmatic calls without `asUser(req)` always set\n   * `isServicePrincipal: true` because no request is available to derive a\n   * user identity from. OBO volume defaults apply only to HTTP route\n   * traffic; for programmatic per-user execution, use `asUser(req)`.\n   */\n  isServicePrincipal?: boolean;\n}\n\n// ---------------------------------------------------------------------------\n// Policy function type\n// ---------------------------------------------------------------------------\n\n/**\n * A policy function that decides whether `user` may perform `action` on\n * `resource`. Return `true` to allow, `false` to deny.\n */\nexport type FilePolicy = (\n  action: FileAction,\n  resource: FileResource,\n  user: FilePolicyUser,\n) => boolean | Promise<boolean>;\n\n// ---------------------------------------------------------------------------\n// PolicyDeniedError\n// ---------------------------------------------------------------------------\n\n/**\n * Thrown when a policy denies an action.\n */\nexport class PolicyDeniedError extends Error {\n  readonly action: FileAction;\n  readonly volumeKey: string;\n\n  constructor(action: FileAction, volumeKey: string) {\n    super(`Policy denied \"${action}\" on volume \"${volumeKey}\"`);\n    this.name = \"PolicyDeniedError\";\n    this.action = action;\n    this.volumeKey = volumeKey;\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Combinators\n// ---------------------------------------------------------------------------\n\n/** Utility namespace with common policy combinators. */\nexport const policy = {\n  /**\n   * AND — all policies must allow. Short-circuits on first denial.\n   */\n  all(...policies: FilePolicy[]): FilePolicy {\n    if (policies.length === 0) {\n      throw new Error(\"policy.all() requires at least one policy\");\n    }\n    return async (action, resource, user) => {\n      for (const p of policies) {\n        if (!(await p(action, resource, user))) return false;\n      }\n      return true;\n    };\n  },\n\n  /**\n   * OR — at least one policy must allow. Short-circuits on first allow.\n   */\n  any(...policies: FilePolicy[]): FilePolicy {\n    if (policies.length === 0) {\n      throw new Error(\"policy.any() requires at least one policy\");\n    }\n    return async (action, resource, user) => {\n      for (const p of policies) {\n        if (await p(action, resource, user)) return true;\n      }\n      return false;\n    };\n  },\n\n  /** Negates a policy. */\n  not(p: FilePolicy): FilePolicy {\n    return async (action, resource, user) => !(await p(action, resource, user));\n  },\n\n  /** Allow all read actions (list, read, download, raw, exists, metadata, preview). */\n  publicRead(): FilePolicy {\n    return (action) => READ_ACTIONS.has(action);\n  },\n\n  /** Deny every action. */\n  denyAll(): FilePolicy {\n    return () => false;\n  },\n\n  /** Allow every action. */\n  allowAll(): FilePolicy {\n    return () => true;\n  },\n} as const;\n"],"mappings":";;AA0BA,MAAa,eAAwC,IAAI,IAAgB;CACvE;CACA;CACA;CACA;CACA;CACA;CACA;CACD,CAAC;;AAGF,MAAa,gBAAyC,IAAI,IAAgB;CACxE;CACA;CACA;CACD,CAAC;;;;AAyEF,IAAa,oBAAb,cAAuC,MAAM;CAC3C,AAAS;CACT,AAAS;CAET,YAAY,QAAoB,WAAmB;AACjD,QAAM,kBAAkB,OAAO,eAAe,UAAU,GAAG;AAC3D,OAAK,OAAO;AACZ,OAAK,SAAS;AACd,OAAK,YAAY;;;;AASrB,MAAa,SAAS;CAIpB,IAAI,GAAG,UAAoC;AACzC,MAAI,SAAS,WAAW,EACtB,OAAM,IAAI,MAAM,4CAA4C;AAE9D,SAAO,OAAO,QAAQ,UAAU,SAAS;AACvC,QAAK,MAAM,KAAK,SACd,KAAI,CAAE,MAAM,EAAE,QAAQ,UAAU,KAAK,CAAG,QAAO;AAEjD,UAAO;;;CAOX,IAAI,GAAG,UAAoC;AACzC,MAAI,SAAS,WAAW,EACtB,OAAM,IAAI,MAAM,4CAA4C;AAE9D,SAAO,OAAO,QAAQ,UAAU,SAAS;AACvC,QAAK,MAAM,KAAK,SACd,KAAI,MAAM,EAAE,QAAQ,UAAU,KAAK,CAAE,QAAO;AAE9C,UAAO;;;CAKX,IAAI,GAA2B;AAC7B,SAAO,OAAO,QAAQ,UAAU,SAAS,CAAE,MAAM,EAAE,QAAQ,UAAU,KAAK;;CAI5E,aAAyB;AACvB,UAAQ,WAAW,aAAa,IAAI,OAAO;;CAI7C,UAAsB;AACpB,eAAa;;CAIf,WAAuB;AACrB,eAAa;;CAEhB"}

package/dist/plugins/files/types.d.ts

@@ -10,6 +10,12 @@ import { files } from "@databricks/sdk-experimental";
 interface VolumeConfig {
   /** Maximum upload size in bytes for this volume. Inherits from plugin-level `maxUploadSize` if not set. */
   maxUploadSize?: number;
+  /**
+   * Maximum byte length the `/read` endpoint will stream before aborting with
+   * `413 Payload Too Large`. Inherits from plugin-level `maxReadSize` if not
+   * set; defaults to 10 MB. `/download` and `/raw` are unaffected.
+   */
+  maxReadSize?: number;
   /** Map of file extensions to MIME types for this volume. Inherits from plugin-level `customContentTypes` if not set. */
   customContentTypes?: Record<string, string>;
   /**
@@ -17,11 +23,70 @@ interface VolumeConfig {
    * service principal and the policy decides whether the action is allowed.
    */
   policy?: FilePolicy;
+  /**
+   * Per-volume auth mode. When `"on-behalf-of-user"`, HTTP route handlers
+   * execute Unity Catalog SDK operations as the end user (using the
+   * `x-forwarded-access-token` and `x-forwarded-user` headers injected by
+   * the Databricks Apps reverse proxy) instead of the service principal.
+   * Inherits from `IFilesConfig.auth` if not set; defaults to
+   * `"service-principal"`.
+   *
+   * **Permission scope**:
+   * - `"service-principal"`: the app's SP needs `WRITE_VOLUME` (or
+   *   read-equivalent) on the UC volume.
+   * - `"on-behalf-of-user"`: each end user needs `WRITE_VOLUME` (or
+   *   read-equivalent) on the UC volume; the SP itself does not need
+   *   direct volume permissions.
+   *
+   * In production, OBO requests with a missing `x-forwarded-access-token`
+   * return `401`. In development (`NODE_ENV === "development"`) they fall
+   * back to the SP with a single warning so local testing without a
+   * reverse proxy continues to work.
+   *
+   * @example Service-principal volume (default)
+   * ```ts
+   * files({
+   *   volumes: {
+   *     exports: {
+   *       auth: "service-principal", // explicit; same as omitting
+   *       policy: files.policy.publicRead(),
+   *     },
+   *   },
+   * });
+   * ```
+   *
+   * @example On-behalf-of-user volume
+   * ```ts
+   * files({
+   *   volumes: {
+   *     "user-uploads": {
+   *       auth: "on-behalf-of-user",
+   *       // Policies see the real end user identity here.
+   *       policy: (action, _resource, user) =>
+   *         !user.isServicePrincipal,
+   *     },
+   *   },
+   * });
+   * ```
+   */
+  auth?: "service-principal" | "on-behalf-of-user";
 }
 /**
  * User-facing API for a single volume.
- * All operations execute as the service principal. When a policy is
- * configured on the volume, every call is checked against that policy.
+ *
+ * Which identity executes each operation depends on the volume's effective
+ * `auth` mode (resolved from `VolumeConfig.auth` ?? `IFilesConfig.auth` ??
+ * `"service-principal"`):
+ * - SP volumes (`auth: "service-principal"`): operations execute as the
+ *   service principal.
+ * - OBO volumes (`auth: "on-behalf-of-user"`): operations invoked through
+ *   the HTTP routes execute as the end user (the token from
+ *   `x-forwarded-access-token` is used to build the SDK client). For
+ *   programmatic calls outside an HTTP route, see `VolumeHandle.asUser(req)`
+ *   to opt into per-user execution explicitly.
+ *
+ * When a policy is configured on the volume, every call is checked against
+ * that policy with the appropriate identity (service principal vs end user).
  */
 interface VolumeAPI {
   list(directoryPath?: string): Promise<DirectoryEntry[]>;
@@ -50,6 +115,47 @@ interface IFilesConfig extends BasePluginConfig {
   customContentTypes?: Record<string, string>;
   /** Maximum upload size in bytes. Defaults to 5 GB (Databricks Files API v2 limit). */
   maxUploadSize?: number;
+  /**
+   * Plugin-level default for the `/read` endpoint's response size cap.
+   * Inherited by volumes without their own `maxReadSize`. Defaults to 10 MB.
+   */
+  maxReadSize?: number;
+  /**
+   * Plugin-level default auth mode for all volumes. Volumes without an
+   * explicit `auth` field inherit this default; volumes that set their own
+   * `VolumeConfig.auth` override it. Defaults to `"service-principal"` if
+   * not set.
+   *
+   * Resolution order (per volume):
+   * `VolumeConfig.auth` > `IFilesConfig.auth` > `"service-principal"`.
+   *
+   * @example Mark every volume OBO unless explicitly overridden
+   * ```ts
+   * files({
+   *   auth: "on-behalf-of-user",
+   *   volumes: {
+   *     // Inherits "on-behalf-of-user" from the plugin-level default.
+   *     "user-uploads": { policy: files.policy.allowAll() },
+   *     // Overrides the plugin default to run as the SP.
+   *     reports: {
+   *       auth: "service-principal",
+   *       policy: files.policy.publicRead(),
+   *     },
+   *   },
+   * });
+   * ```
+   *
+   * @example Default to service-principal (the implicit default)
+   * ```ts
+   * files({
+   *   // No `auth` set → all volumes default to "service-principal".
+   *   volumes: {
+   *     exports: { policy: files.policy.publicRead() },
+   *   },
+   * });
+   * ```
+   */
+  auth?: "service-principal" | "on-behalf-of-user";
 }
 /** A single entry returned when listing a directory. Re-exported from `@databricks/sdk-experimental`. */
 type DirectoryEntry = files.DirectoryEntry;
@@ -80,9 +186,34 @@ interface FilePreview extends FileMetadata {
 /**
  * Volume handle returned by `app.files("volumeKey")`.
  *
- * All methods execute as the service principal and enforce the volume's
- * policy (if configured) with `{ isServicePrincipal: true }`.
- * `asUser(req)` re-wraps with the real user identity for per-user policy checks.
+ * Default execution identity follows the volume's effective `auth` mode:
+ * - SP volumes (`auth: "service-principal"`): methods execute as the service
+ *   principal and the volume policy (if configured) sees
+ *   `{ isServicePrincipal: true }`.
+ * - OBO volumes (`auth: "on-behalf-of-user"`): methods invoked from inside
+ *   an HTTP route handler execute as the end user (the route wires the
+ *   request token into a `runInUserContext` scope before calling SDK code).
+ *
+ * `asUser(req)` is a hard override: regardless of the volume's `auth`
+ * setting (SP or OBO), the returned API runs every SDK call inside
+ * `runInUserContext` with the user identity extracted from the request,
+ * so the underlying `WorkspaceClient` is the user-token client. This makes
+ * `appKit.files("sp-vol").asUser(req).list()` actually execute as the end
+ * user, even on a service-principal-configured volume.
+ *
+ * In production `asUser` throws `AuthenticationError.missingToken` when the
+ * `x-forwarded-user` header is missing. In development
+ * (`NODE_ENV === "development"`) it logs a warning and falls back to the
+ * service principal so local testing without a reverse proxy continues to
+ * work — in that fallback no `runInUserContext` wrap is applied and SDK
+ * calls execute as the SP, identical to pre-OBO behavior.
+ *
+ * @remarks Behavior change: prior to OBO support, `asUser(req)` only
+ * influenced the policy user passed to the volume policy — the underlying
+ * SDK call still ran as the service principal. With OBO support landed,
+ * `asUser` now also forces the SDK call to run as the user. Any caller
+ * that relied on the pre-OBO behavior (policy sees user, SDK runs as SP)
+ * must remove the `asUser` wrap.
  */
 type VolumeHandle = VolumeAPI & {
   asUser: (req: IAppRequest) => VolumeAPI;