feat(files): per-volume in-app policy enforcement

apps/dev-playground/server/index.ts

@@ -32,7 +32,7 @@ createApp({
       spaces: { demo: process.env.DATABRICKS_GENIE_SPACE_ID ?? "placeholder" },
     }),
     lakebaseExamples(),
-    files(),
+    files({ volumes: { default: { policy: files.policy.allowAll() } } }),
     serving(),
   ],
   ...(process.env.APPKIT_E2E_TEST && { client: createMockClient() }),

docs/docs/api/appkit/Class.PolicyDeniedError.md

@@ -0,0 +1,48 @@
+# Class: PolicyDeniedError
+
+Thrown when a policy denies an action.
+
+## Extends
+
+- `Error`
+
+## Constructors
+
+### Constructor
+
+```ts
+new PolicyDeniedError(action: FileAction, volumeKey: string): PolicyDeniedError;
+```
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `action` | [`FileAction`](TypeAlias.FileAction.md) |
+| `volumeKey` | `string` |
+
+#### Returns
+
+`PolicyDeniedError`
+
+#### Overrides
+
+```ts
+Error.constructor
+```
+
+## Properties
+
+### action
+
+```ts
+readonly action: FileAction;
+```
+
+***
+
+### volumeKey
+
+```ts
+readonly volumeKey: string;
+```

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

@@ -0,0 +1,21 @@
+# Interface: FilePolicyUser
+
+Minimal user identity passed to the policy function.
+
+## Properties
+
+### id
+
+```ts
+id: string;
+```
+
+***
+
+### isServicePrincipal?
+
+```ts
+optional isServicePrincipal: boolean;
+```
+
+`true` when the caller is the service principal (direct SDK call, not `asUser`).

docs/docs/api/appkit/Interface.FileResource.md

@@ -0,0 +1,33 @@
+# Interface: FileResource
+
+Describes the file or directory being acted upon.
+
+## Properties
+
+### path
+
+```ts
+path: string;
+```
+
+Relative path within the volume.
+
+***
+
+### size?
+
+```ts
+optional size: number;
+```
+
+Content length in bytes — only present for uploads.
+
+***
+
+### volume
+
+```ts
+volume: string;
+```
+
+The volume key (e.g. `"uploads"`).

docs/docs/api/appkit/TypeAlias.FileAction.md

@@ -0,0 +1,17 @@
+# Type Alias: FileAction
+
+```ts
+type FileAction = 
+  | "list"
+  | "read"
+  | "download"
+  | "raw"
+  | "exists"
+  | "metadata"
+  | "preview"
+  | "upload"
+  | "mkdir"
+  | "delete";
+```
+
+Every action the files plugin can perform.

docs/docs/api/appkit/TypeAlias.FilePolicy.md

@@ -0,0 +1,20 @@
+# Type Alias: FilePolicy()
+
+```ts
+type FilePolicy = (action: FileAction, resource: FileResource, user: FilePolicyUser) => boolean | Promise<boolean>;
+```
+
+A policy function that decides whether `user` may perform `action` on
+`resource`. Return `true` to allow, `false` to deny.
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `action` | [`FileAction`](TypeAlias.FileAction.md) |
+| `resource` | [`FileResource`](Interface.FileResource.md) |
+| `user` | [`FilePolicyUser`](Interface.FilePolicyUser.md) |
+
+## Returns
+
+`boolean` \| `Promise`\<`boolean`\>

docs/docs/api/appkit/Variable.READ_ACTIONS.md

@@ -0,0 +1,7 @@
+# Variable: READ\_ACTIONS
+
+```ts
+const READ_ACTIONS: ReadonlySet<FileAction>;
+```
+
+Actions that only read data.

docs/docs/api/appkit/Variable.WRITE_ACTIONS.md

@@ -0,0 +1,7 @@
+# Variable: WRITE\_ACTIONS
+
+```ts
+const WRITE_ACTIONS: ReadonlySet<FileAction>;
+```
+
+Actions that mutate data.

docs/docs/api/appkit/index.md

@@ -21,6 +21,7 @@ plugin architecture, and React integration.
 | [ExecutionError](Class.ExecutionError.md) | Error thrown when an operation execution fails. Use for statement failures, canceled operations, or unexpected states. |
 | [InitializationError](Class.InitializationError.md) | Error thrown when a service or component is not properly initialized. Use when accessing services before they are ready. |
 | [Plugin](Class.Plugin.md) | Base abstract class for creating AppKit plugins. |
+| [PolicyDeniedError](Class.PolicyDeniedError.md) | Thrown when a policy denies an action. |
 | [ResourceRegistry](Class.ResourceRegistry.md) | Central registry for tracking plugin resource requirements. Deduplication uses type + resourceKey (machine-stable); alias is for display only. |
 | [ServerError](Class.ServerError.md) | Error thrown when server lifecycle operations fail. Use for server start/stop issues, configuration conflicts, etc. |
 | [TunnelError](Class.TunnelError.md) | Error thrown when remote tunnel operations fail. Use for tunnel connection issues, message parsing failures, etc. |
@@ -34,6 +35,8 @@ plugin architecture, and React integration.
 | [CacheConfig](Interface.CacheConfig.md) | Configuration for the CacheInterceptor. Controls TTL, size limits, storage backend, and probabilistic cleanup. |
 | [DatabaseCredential](Interface.DatabaseCredential.md) | Database credentials with OAuth token for Postgres connection |
 | [EndpointConfig](Interface.EndpointConfig.md) | - |
+| [FilePolicyUser](Interface.FilePolicyUser.md) | Minimal user identity passed to the policy function. |
+| [FileResource](Interface.FileResource.md) | Describes the file or directory being acted upon. |
 | [GenerateDatabaseCredentialRequest](Interface.GenerateDatabaseCredentialRequest.md) | Request parameters for generating database OAuth credentials |
 | [ITelemetry](Interface.ITelemetry.md) | Plugin-facing interface for OpenTelemetry instrumentation. Provides a thin abstraction over OpenTelemetry APIs for plugins. |
 | [LakebasePoolConfig](Interface.LakebasePoolConfig.md) | Configuration for creating a Lakebase connection pool |
@@ -55,6 +58,8 @@ plugin architecture, and React integration.
 | ------ | ------ |
 | [ConfigSchema](TypeAlias.ConfigSchema.md) | Configuration schema definition for plugin config. Re-exported from the standard JSON Schema Draft 7 types. |
 | [ExecutionResult](TypeAlias.ExecutionResult.md) | Discriminated union for plugin execution results. |
+| [FileAction](TypeAlias.FileAction.md) | Every action the files plugin can perform. |
+| [FilePolicy](TypeAlias.FilePolicy.md) | A policy function that decides whether `user` may perform `action` on `resource`. Return `true` to allow, `false` to deny. |
 | [IAppRouter](TypeAlias.IAppRouter.md) | Express router type for plugin route registration |
 | [PluginData](TypeAlias.PluginData.md) | Tuple of plugin class, config, and name. Created by `toPlugin()` and passed to `createApp()`. |
 | [ResourcePermission](TypeAlias.ResourcePermission.md) | Union of all possible permission levels across all resource types. |
@@ -65,7 +70,9 @@ plugin architecture, and React integration.
 
 | Variable | Description |
 | ------ | ------ |
+| [READ\_ACTIONS](Variable.READ_ACTIONS.md) | Actions that only read data. |
 | [sql](Variable.sql.md) | SQL helper namespace |
+| [WRITE\_ACTIONS](Variable.WRITE_ACTIONS.md) | Actions that mutate data. |
 
 ## Functions
 

docs/docs/api/appkit/typedoc-sidebar.ts

@@ -56,6 +56,11 @@ const typedocSidebar: SidebarsConfig = {
           id: "api/appkit/Class.Plugin",
           label: "Plugin"
         },
+        {
+          type: "doc",
+          id: "api/appkit/Class.PolicyDeniedError",
+          label: "PolicyDeniedError"
+        },
         {
           type: "doc",
           id: "api/appkit/Class.ResourceRegistry",
@@ -102,6 +107,16 @@ const typedocSidebar: SidebarsConfig = {
           id: "api/appkit/Interface.EndpointConfig",
           label: "EndpointConfig"
         },
+        {
+          type: "doc",
+          id: "api/appkit/Interface.FilePolicyUser",
+          label: "FilePolicyUser"
+        },
+        {
+          type: "doc",
+          id: "api/appkit/Interface.FileResource",
+          label: "FileResource"
+        },
         {
           type: "doc",
           id: "api/appkit/Interface.GenerateDatabaseCredentialRequest",
@@ -188,6 +203,16 @@ const typedocSidebar: SidebarsConfig = {
           id: "api/appkit/TypeAlias.ExecutionResult",
           label: "ExecutionResult"
         },
+        {
+          type: "doc",
+          id: "api/appkit/TypeAlias.FileAction",
+          label: "FileAction"
+        },
+        {
+          type: "doc",
+          id: "api/appkit/TypeAlias.FilePolicy",
+          label: "FilePolicy"
+        },
         {
           type: "doc",
           id: "api/appkit/TypeAlias.IAppRouter",
@@ -219,10 +244,20 @@ const typedocSidebar: SidebarsConfig = {
       type: "category",
       label: "Variables",
       items: [
+        {
+          type: "doc",
+          id: "api/appkit/Variable.READ_ACTIONS",
+          label: "READ_ACTIONS"
+        },
         {
           type: "doc",
           id: "api/appkit/Variable.sql",
           label: "sql"
+        },
+        {
+          type: "doc",
+          id: "api/appkit/Variable.WRITE_ACTIONS",
+          label: "WRITE_ACTIONS"
         }
       ]
     },

docs/docs/plugins/execution-context.md

@@ -41,7 +41,6 @@ Exported from `@databricks/appkit`:
 - `getWorkspaceClient()`: Returns the appropriate WorkspaceClient for current context
 - `getWarehouseId()`: `Promise<string>` (from `DATABRICKS_WAREHOUSE_ID` or auto-selected in dev)
 - `getWorkspaceId()`: `Promise<string>` (from `DATABRICKS_WORKSPACE_ID` or fetched)
-- `isInUserContext()`: Returns `true` if currently executing in user context
 
 ## Development mode behavior