@databricks/appkit 0.35.0 → 0.35.2

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","names":[],"sources":["../../../src/plugins/files/types.ts"],"mappings":";;;;;;;;;UAOiB,YAAA;EAAY;EAE3B,aAAA;EAOmB;EALnB,kBAAA,GAAqB,MAAA;EAArB;;;;EAKA,MAAA,GAAS,UAAA;AAAA;AAQX;;;;;AAAA,UAAiB,SAAA;EACf,IAAA,CAAK,aAAA,YAAyB,OAAA,CAAQ,cAAA;EACtC,IAAA,CAAK,QAAA,UAAkB,OAAA;IAAY,OAAA;EAAA,IAAqB,OAAA;EACxD,QAAA,CAAS,QAAA,WAAmB,OAAA,CAAQ,gBAAA;EACpC,MAAA,CAAO,QAAA,WAAmB,OAAA;EAC1B,QAAA,CAAS,QAAA,WAAmB,OAAA,CAAQ,YAAA;EACpC,MAAA,CACE,QAAA,UACA,QAAA,EAAU,cAAA,GAAiB,MAAA,WAC3B,OAAA;IAAY,SAAA;EAAA,IACX,OAAA;EACH,eAAA,CAAgB,aAAA,WAAwB,OAAA;EACxC,MAAA,CAAO,QAAA,WAAmB,OAAA;EAC1B,OAAA,CAAQ,QAAA,WAAmB,OAAA,CAAQ,WAAA;AAAA;;;;UAMpB,YAAA,SAAqB,gBAAA;EAjBpC;EAmBA,OAAA;EAnBmC;EAqBnC,OAAA,GAAU,MAAA,SAAe,YAAA;EArB+B;EAuBxD,kBAAA,GAAqB,MAAA;EAtBZ;EAwBT,aAAA;AAAA;;KAIU,cAAA,GAAiB,KAAA,CAAM,cAAA;;KAGvB,gBAAA,GAAmB,KAAA,CAAM,gBAAA;;;;UAKpB,YAAA;EAhCb;EAkCF,aAAA;EAjC6B;EAmC7B,WAAA;EAlCc;EAoCd,YAAA;AAAA;;;;UAMe,WAAA,SAAoB,YAAA;EAvC5B;EAyCP,WAAA;EAxCA;EA0CA,MAAA;EA1C2B;EA4C3B,OAAA;AAAA;;AAtCF;;;;;;KAgDY,YAAA,GAAe,SAAA;EACzB,MAAA,GAAS,GAAA,EAAK,WAAA,KAAgB,SAAA;AAAA;;;;;;;;;;;AArChC;;;;;AAGA;;UAsDiB,WAAA;EAAA,CACd,SAAA,WAAoB,YAAA;EACrB,MAAA,GAAS,SAAA,aAAsB,YAAA;AAAA"}
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../../src/plugins/files/types.ts"],"mappings":";;;;;;;;;UAOiB,YAAA;EAAY;EAE3B,aAAA;EAamB;;;;;EAPnB,WAAA;EAOS;EALT,kBAAA,GAAqB,MAAA;EAoDjB;;AAoBN;;EAnEE,MAAA,GAAS,UAAA;EAoE6B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EArBtC,IAAA;AAAA;;;;;;;;;;AAuCF;;;;;;;;UAnBiB,SAAA;EACf,IAAA,CAAK,aAAA,YAAyB,OAAA,CAAQ,cAAA;EACtC,IAAA,CAAK,QAAA,UAAkB,OAAA;IAAY,OAAA;EAAA,IAAqB,OAAA;EACxD,QAAA,CAAS,QAAA,WAAmB,OAAA,CAAQ,gBAAA;EACpC,MAAA,CAAO,QAAA,WAAmB,OAAA;EAC1B,QAAA,CAAS,QAAA,WAAmB,OAAA,CAAQ,YAAA;EACpC,MAAA,CACE,QAAA,UACA,QAAA,EAAU,cAAA,GAAiB,MAAA,WAC3B,OAAA;IAAY,SAAA;EAAA,IACX,OAAA;EACH,eAAA,CAAgB,aAAA,WAAwB,OAAA;EACxC,MAAA,CAAO,QAAA,WAAmB,OAAA;EAC1B,OAAA,CAAQ,QAAA,WAAmB,OAAA,CAAQ,WAAA;AAAA;;;;UAMpB,YAAA,SAAqB,gBAAA;EAwDV;EAtD1B,OAAA;EAsD6B;EApD7B,OAAA,GAAU,MAAA,SAAe,YAAA;EAyDV;EAvDf,kBAAA,GAAqB,MAAA;;EAErB,aAAA;EAuDA;;;;EAlDA,WAAA;EA4De;;;;;;;;;;AAyCjB;;;;;;;;;;;;;;;AAqBA;;;;;;;;;;EAtFE,IAAA;AAAA;;KAIU,cAAA,GAAiB,KAAA,CAAM,cAAA;;KAGvB,gBAAA,GAAmB,KAAA,CAAM,gBAAA;;;;UAKpB,YAAA;;EAEf,aAAA;;EAEA,WAAA;;EAEA,YAAA;AAAA;;;;UAMe,WAAA,SAAoB,YAAA;;EAEnC,WAAA;;EAEA,MAAA;;EAEA,OAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAmCU,YAAA,GAAe,SAAA;EACzB,MAAA,GAAS,GAAA,EAAK,WAAA,KAAgB,SAAA;AAAA;;;;;;;;;;;;;;;;;;UAoBf,WAAA;EAAA,CACd,SAAA,WAAoB,YAAA;EACrB,MAAA,GAAS,SAAA,aAAsB,YAAA;AAAA"}

package/docs/api/appkit/Interface.FilePolicyUser.md

@@ -11,6 +11,8 @@ id: string;
 
 ```
 
+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.
+
 ***
 
 ### isServicePrincipal?[​](#isserviceprincipal "Direct link to isServicePrincipal?")
@@ -20,4 +22,16 @@ optional isServicePrincipal: boolean;
 
 ```
 
-`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)`.

package/docs/development/llm-guide.md

@@ -24,7 +24,6 @@ This guide is designed to work even when you *do not* have access to the AppKit
 
 * **Do not invent APIs**. If unsure, stick to the patterns shown in the documentation and only use documented exports from `@databricks/appkit` and `@databricks/appkit-ui`.
 * **`createApp()` is async**. Prefer **top-level `await createApp(...)`**. If you can't, use `void createApp(...)` and do not ignore promise rejection.
-* **Always memoize query parameters** passed to `useAnalyticsQuery` / charts to avoid refetch loops.
 * **Always handle loading/error/empty states** in UI (use `Skeleton`, error text, empty state).
 * **Always use `sql.*` helpers** for query parameters (do not pass raw strings/numbers unless the query expects none).
 * **Never construct SQL strings dynamically**. Use parameterized queries with `:paramName`.

package/docs/plugins/files.md

@@ -11,7 +11,7 @@ File operations against Databricks Unity Catalog Volumes. Supports listing, read
 * Upload size limits with streaming enforcement
 * Automatic cache invalidation on write operations
 * Custom content type mappings
-* Per-user execution context (OBO)
+* **Per-volume auth modes**: each volume can run as the service principal (the default) or on behalf of the end user
 * **Access policies**: Per-volume policy functions that gate read and write operations
 
 ## Basic usage[​](#basic-usage "Direct link to Basic usage")
@@ -73,6 +73,11 @@ interface IFilesConfig {
   customContentTypes?: Record<string, string>;
   /** Maximum upload size in bytes. Defaults to 5 GB. Inherited by all volumes. */
   maxUploadSize?: number;
+  /**
+   * Plugin-level default auth mode. Volumes inherit this when they do not
+   * set `VolumeConfig.auth`. Defaults to `"service-principal"`.
+   */
+  auth?: "service-principal" | "on-behalf-of-user";
 }
 
 interface VolumeConfig {
@@ -82,6 +87,11 @@ interface VolumeConfig {
   maxUploadSize?: number;
   /** Map of file extensions to MIME types for this volume. Overrides plugin-level default. */
   customContentTypes?: Record<string, string>;
+  /**
+   * Per-volume auth mode. Inherits from `IFilesConfig.auth` when not set;
+   * defaults to `"service-principal"`.
+   */
+  auth?: "service-principal" | "on-behalf-of-user";
 }
 
 ```
@@ -102,6 +112,80 @@ files({
 
 ```
 
+### Auth modes[​](#auth-modes "Direct link to Auth modes")
+
+Each volume runs in one of two auth modes. The mode determines which identity executes the underlying Unity Catalog SDK call — and therefore which UC grant applies:
+
+| Mode                            | SDK identity                  | Required UC grant on the volume                         |
+| ------------------------------- | ----------------------------- | ------------------------------------------------------- |
+| `"service-principal"` (default) | the app's service principal   | `WRITE_VOLUME` (or read-equivalent) on the **SP**       |
+| `"on-behalf-of-user"`           | the end user from the request | `WRITE_VOLUME` (or read-equivalent) on the **end user** |
+
+#### Resolution order[​](#resolution-order "Direct link to Resolution order")
+
+For each volume the plugin resolves the auth mode in this order:
+
+```text
+VolumeConfig.auth  >  IFilesConfig.auth  >  "service-principal"
+
+```
+
+Set `IFilesConfig.auth` to flip the default for every volume in one place, and override individual volumes via `VolumeConfig.auth`.
+
+#### Service-principal mode (default)[​](#service-principal-mode-default "Direct link to Service-principal mode (default)")
+
+Every HTTP request executes as the app's service principal. The end-user identity (from `x-forwarded-user`) is still passed into the volume policy, but the SDK call uses the SP's credentials:
+
+```ts
+files({
+  volumes: {
+    exports: {
+      // auth is implicit: "service-principal"
+      policy: files.policy.publicRead(),
+    },
+  },
+});
+
+```
+
+Use SP mode for shared resources, app-managed exports, or any case where you want a single grant on the SP to govern all access.
+
+#### On-behalf-of-user mode[​](#on-behalf-of-user-mode "Direct link to On-behalf-of-user mode")
+
+Every HTTP request executes as the end user. The plugin pulls the user identity and access token from the headers Databricks Apps inject (`x-forwarded-user` and `x-forwarded-access-token`) and runs the SDK call inside `runInUserContext`:
+
+```ts
+files({
+  volumes: {
+    "user-uploads": {
+      auth: "on-behalf-of-user",
+      // The policy sees the real end user (isServicePrincipal: false).
+      // You can use the volume policy in addition to UC grants.
+      policy: (action, _resource, user) =>
+        // Only allow real end users, never the SP.
+        !user.isServicePrincipal,
+    },
+  },
+});
+
+```
+
+Use OBO mode when the per-user UC grant is meaningful — e.g. enforcement of UC ACLs at the SDK layer, or audit trails that need to attribute the API call to the end user instead of the app's SP.
+
+#### Production vs development behavior[​](#production-vs-development-behavior "Direct link to Production vs development behavior")
+
+| Environment                                | OBO request with **valid** token | OBO request with **missing** `x-forwarded-access-token` |
+| ------------------------------------------ | -------------------------------- | ------------------------------------------------------- |
+| Production                                 | Runs as the end user.            | `401 Unauthorized` — no SDK call is made.               |
+| Development (`NODE_ENV === "development"`) | Runs as the end user.            | Logs a warning, falls back to the SP, and continues.    |
+
+The dev-mode fallback exists so local testing without a Databricks Apps reverse proxy continues to work; deployed apps always have the headers injected.
+
+#### Limitations[​](#limitations "Direct link to Limitations")
+
+* The plugin manifest's `getResourceRequirements()` declares `WRITE_VOLUME` on the **service principal** for every volume, regardless of the volume's `auth` mode. For OBO volumes, the actual permission requirement is on the **end user** — communicate this out-of-band (deployment runbooks, customer onboarding docs) until the plugin manifest schema gains a per-volume auth scope field.
+* OBO volumes disable the read/list cache entirely. The cache layer keys by `getCurrentUserId()`, so a write by user A wouldn't invalidate user B's view of the same path; rather than risk cross-user staleness, OBO traffic skips the cache and fetches fresh on every request. SP volumes still cache (single slice keyed by the SP id).
+
 ### Permission model[​](#permission-model "Direct link to Permission model")
 
 There are three layers of access control in the files plugin. Understanding how they interact is critical for securing your app:
@@ -109,11 +193,14 @@ There are three layers of access control in the files plugin. Understanding how
 ```text
 ┌─────────────────────────────────────────────────┐
 │  Unity Catalog grants                           │
-│  (WRITE_VOLUME on the SP — set at deploy time)  │
+│  WRITE_VOLUME on the SP (auth: service-principal)│
+│  WRITE_VOLUME on the user (auth: on-behalf-of-user)│
 ├─────────────────────────────────────────────────┤
 │  Execution identity                             │
-│  HTTP routes → always service principal         │
-│  Programmatic → SP by default, asUser() for OBO │
+│  Resolved per volume from VolumeConfig.auth ??  │
+│  IFilesConfig.auth ?? "service-principal".      │
+│  asUser(req) is a hard override at the SDK     │
+│  level for the programmatic API.                │
 ├─────────────────────────────────────────────────┤
 │  File policies                                  │
 │  Per-volume (action, resource, user) → boolean  │
@@ -122,13 +209,15 @@ There are three layers of access control in the files plugin. Understanding how
 
 ```
 
-* **UC grants** control what the service principal can do at the Databricks level. These are set at deploy time via `app.yaml` resource bindings. The SP needs `WRITE_VOLUME` — the plugin declares this via resource requirements.
-* **Execution identity** determines whose credentials are used for the actual API call. HTTP routes always use the SP. The programmatic API uses SP by default but supports `asUser(req)` for OBO.
-* **File policies** are application-level checks evaluated **before** the API call. They receive the requesting user's identity (from the `x-forwarded-user` header) and decide allow/deny. This is the only gate that distinguishes between users on HTTP routes.
+* **UC grants** control what an identity can do at the Databricks level. Which identity needs the grant depends on the volume's auth mode (see [Auth modes](#auth-modes)). For SP volumes, the SP needs `WRITE_VOLUME` (the plugin declares this in its manifest). For OBO volumes, the **end user** needs `WRITE_VOLUME` on the volume; the SP itself does not.
+* **Execution identity** determines whose credentials are used for the actual API call. Each volume resolves to either the service principal or the end user, per its `auth` setting. The programmatic API also exposes `asUser(req)` to force per-user execution regardless of the volume's `auth`.
+* **File policies** are application-level checks evaluated **before** the API call. They receive a `FilePolicyUser` describing the caller and decide allow/deny. On HTTP routes the policy user is selected based on the volume's `auth` mode and the request headers — see the [`isServicePrincipal` matrix](#policy-user-matrix). On SP volumes when `x-forwarded-user` is absent, the policy receives `{ id: <sp-id>, isServicePrincipal: true }` and decides whether to allow service-principal traffic. This is the only gate that distinguishes between users on HTTP routes.
 
 warning
 
-Since HTTP routes always execute as the service principal, removing a user's UC `WRITE_VOLUME` grant has **no effect** on HTTP access — the SP's grant is what's used. Policies are how you restrict what individual users can do through your app.
+For service-principal volumes, every HTTP request executes as the SP regardless of which user made it — so removing a user's UC `WRITE_VOLUME` grant has **no effect** on HTTP access. Policies are how you restrict what individual users can do through your app.
+
+For on-behalf-of-user volumes, requests execute as the requesting user — so each user must have `WRITE_VOLUME` on the volume themselves, and you can rely on UC grants in addition to policies.
 
 New in v0.21.0
 
@@ -211,6 +300,58 @@ files({
 
 ```
 
+#### OBO policy example[​](#obo-policy-example "Direct link to OBO policy example")
+
+For on-behalf-of-user volumes, the policy receives `isServicePrincipal: false` whenever the request runs with a real end-user identity. A common pattern is to deny SP traffic outright so anonymous (header-less) calls can't reach the volume:
+
+```ts
+import { type FilePolicy } from "@databricks/appkit";
+
+// Deny anything running as the service principal — including the dev-mode
+// fallback when no x-forwarded-access-token was provided. Real end users
+// (with isServicePrincipal: false) get the configured access.
+const usersOnly: FilePolicy = (_action, _resource, user) => {
+  return user.isServicePrincipal !== true;
+};
+
+files({
+  volumes: {
+    "user-uploads": {
+      auth: "on-behalf-of-user",
+      policy: usersOnly,
+    },
+  },
+});
+
+```
+
+You can compose it with any other policy via `files.policy.all(...)` to add per-action gating:
+
+```ts
+files({
+  volumes: {
+    "user-uploads": {
+      auth: "on-behalf-of-user",
+      policy: files.policy.all(usersOnly, files.policy.publicRead()),
+    },
+  },
+});
+
+```
+
+#### Policy user matrix[​](#policy-user-matrix "Direct link to Policy user matrix")
+
+The plugin selects the policy user based on the volume's effective `auth` mode and the request headers. The full table:
+
+| 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`.        |
+| any                 | Programmatic (no `asUser`) | n/a                         | `true`               | No request available to derive a user — runs as the SP.                                     |
+
 #### Enforcement[​](#enforcement "Direct link to Enforcement")
 
 * **HTTP routes**: Policy checked before every operation. Denied → `403` JSON response with `Policy denied "{action}" on volume "{volumeKey}"`.
@@ -236,7 +377,7 @@ Dangerous MIME types (`text/html`, `text/javascript`, `application/javascript`,
 
 ## HTTP routes[​](#http-routes "Direct link to HTTP routes")
 
-Routes are mounted at `/api/files/*`. All routes execute as the service principal. Policy enforcement checks user identity (from the `x-forwarded-user` header) before allowing operations — see [Access policies](#access-policies).
+Routes are mounted at `/api/files/*`. Each route resolves the volume's [auth mode](#auth-modes) and either executes as the service principal (the default) or wraps the SDK call in `runInUserContext` for OBO volumes. Before every operation the volume policy runs against the resolved policy user — see the [policy user matrix](#policy-user-matrix) for the exact mapping. See also [Access policies](#access-policies).
 
 | Method | Path                   | Query / Body                 | Response                                                     |
 | ------ | ---------------------- | ---------------------------- | ------------------------------------------------------------ |
@@ -292,22 +433,37 @@ Write operations (`upload`, `mkdir`, `delete`) automatically invalidate the cach
 
 ## Programmatic API[​](#programmatic-api "Direct link to Programmatic API")
 
-The `exports()` API is a callable that accepts a volume key and returns a `VolumeHandle`. The handle exposes all `VolumeAPI` methods directly (service principal, logs a warning) and an `asUser(req)` method for OBO access (recommended).
+The `files` plugin export is a callable that accepts a volume key and returns a `VolumeHandle`. The handle exposes all `VolumeAPI` methods directly and an `asUser(req)` method for opting into per-user execution.
 
 ```ts
-// OBO access (recommended)
+// Default — runs as the service principal, regardless of the volume's auth
+// setting (no req is available to derive a user from).
+const entries = await appkit.files("uploads").list();
+
+// asUser(req) — runs as the end user, regardless of the volume's auth
+// setting. Forces SDK calls into runInUserContext using the request's
+// x-forwarded-user / x-forwarded-access-token headers.
 const entries = await appkit.files("uploads").asUser(req).list();
 const content = await appkit.files("exports").asUser(req).read("report.csv");
 
-// Service principal access (logs a warning encouraging OBO)
-const entries = await appkit.files("uploads").list();
-
 // Named accessor
 const vol = appkit.files.volume("uploads");
 await vol.asUser(req).list();
 
 ```
 
+### `asUser(req)`[​](#asuserreq "Direct link to asuserreq")
+
+`asUser(req)` is the supported path for programmatic per-user execution. The returned API runs every method inside `runInUserContext` so the underlying `WorkspaceClient` is the user-token client — the SDK call executes as the user, not just the policy check.
+
+In production, `asUser(req)` throws `AuthenticationError.missingToken` when either `x-forwarded-user` or `x-forwarded-access-token` is absent — both headers are required to mint a user-scoped client. In development (`NODE_ENV === "development"`) it logs a warning and falls back to the service principal so local testing without a Databricks Apps reverse proxy keeps working — the fallback skips the `runInUserContext` wrap.
+
+Programmatic OBO without `asUser(req)`
+
+A volume configured with `auth: "on-behalf-of-user"` only routes through `runInUserContext` on the **HTTP route path**, where the request headers are available. A direct programmatic call — `appkit.files("obo-vol").list()` — has no request to derive an end-user identity from, so it executes against whatever client `getWorkspaceClient()` resolves to at the call site (typically the SP at the top level).
+
+For programmatic per-user execution, always use `asUser(req)`. The volume's `auth` mode controls HTTP traffic; `asUser(req)` controls programmatic traffic.
+
 ### VolumeAPI methods[​](#volumeapi-methods "Direct link to VolumeAPI methods")
 
 | Method            | Signature                                                                                             | Returns            |
@@ -375,9 +531,20 @@ interface FileResource {
 }
 
 interface FilePolicyUser {
-  /** User ID from the `x-forwarded-user` header. */
+  /**
+   * 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(...)` without `asUser`), an HTTP request
+   * with no forwarded headers, or the dev-mode fallback for an OBO volume
+   * with a missing token. See the [policy user matrix](#policy-user-matrix)
+   * for the full table.
+   */
   isServicePrincipal?: boolean;
 }
 
@@ -394,6 +561,11 @@ interface VolumeConfig {
   maxUploadSize?: number;
   /** Map of file extensions to MIME types for this volume. */
   customContentTypes?: Record<string, string>;
+  /**
+   * Per-volume auth mode. Inherits from `IFilesConfig.auth` when not set;
+   * defaults to `"service-principal"`.
+   */
+  auth?: "service-principal" | "on-behalf-of-user";
 }
 
 interface VolumeAPI {
@@ -408,7 +580,10 @@ interface VolumeAPI {
   preview(filePath: string): Promise<FilePreview>;
 }
 
-/** Volume handle: all VolumeAPI methods (service principal) + asUser() for OBO. */
+/**
+ * Volume handle: all VolumeAPI methods (run as the service principal by
+ * default) + asUser() to force per-user execution at the SDK level.
+ */
 type VolumeHandle = VolumeAPI & {
   asUser: (req: Request) => VolumeAPI;
 };
@@ -427,9 +602,12 @@ Built-in extensions: `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.svg`, `.bmp`, `
 
 ## User context[​](#user-context "Direct link to User context")
 
-HTTP routes always execute as the **service principal** — the SP's Databricks credentials are used for all API calls. User identity is extracted from the `x-forwarded-user` header and passed to the volume's [access policy](#access-policies) for authorization. This means UC grants on the SP (not individual users) determine what operations are possible, while policies control what each user is allowed to do through the app.
+HTTP routes execute as either the service principal or the end user, depending on the volume's [auth mode](#auth-modes):
 
-The programmatic API returns a `VolumeHandle` that exposes all `VolumeAPI` methods directly (service principal) and an `asUser(req)` method for OBO access. Calling any method without `asUser()` logs a warning encouraging OBO usage but does not throw. OBO access is strongly recommended for production use.
+* **Service-principal volumes** (the default): the SP's Databricks credentials are used for the API call. User identity is extracted from the `x-forwarded-user` header and passed to the volume's [access policy](#access-policies) for authorization, but the SDK call still runs as the SP. When the header is absent the policy is handed `{ id: <sp-id>, isServicePrincipal: true }` and decides whether to allow the call — in practice that branch only fires in development without a reverse proxy or when an upstream proxy is misconfigured, since real Databricks Apps runtimes always forward the header. UC grants on the **SP** determine what operations are possible.
+* **On-behalf-of-user volumes**: the end user's access token (from `x-forwarded-access-token`) is used to mint the SDK client, so the API call runs with the user's identity. Both the policy and the SDK see the user. UC grants on the **end user** determine what operations are possible. In production, requests with a missing token return `401`; in development (`NODE_ENV === "development"`) they fall back to the SP with a warning.
+
+The programmatic API returns a `VolumeHandle` that exposes all `VolumeAPI` methods directly and an `asUser(req)` method for forcing per-user execution. Calling a method without `asUser()` runs the policy and the SDK call as the SP. `asUser(req)` is a hard override at the SDK level: it forces every subsequent call to execute as the end user inside `runInUserContext`, regardless of the volume's `auth` setting. In production, `asUser(req)` throws `AuthenticationError.missingToken` when either `x-forwarded-user` or `x-forwarded-access-token` is absent — both headers are required. In development it falls back to the service principal instead, so local testing without a reverse proxy continues to work.
 
 ## Resource requirements[​](#resource-requirements "Direct link to Resource requirements")
 
@@ -437,6 +615,8 @@ Volume resources are declared **dynamically** via `getResourceRequirements(confi
 
 For example, if `DATABRICKS_VOLUME_UPLOADS` and `DATABRICKS_VOLUME_EXPORTS` are set, calling `files()` generates two required volume resources validated at startup — no explicit `volumes` config needed.
 
+The manifest declares the grant against the **service principal**. For OBO volumes (`auth: "on-behalf-of-user"`), the actual permission requirement is on the **end user** — communicate this out-of-band in your deployment documentation until the manifest schema gains a per-volume auth scope field.
+
 ## Error responses[​](#error-responses "Direct link to Error responses")
 
 All errors return JSON:

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@databricks/appkit",
   "type": "module",
-  "version": "0.35.0",
+  "version": "0.35.2",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "packageManager": "pnpm@10.21.0",