@databricks/appkit 0.23.0 → 0.25.0

package/dist/index.js

@@ -24,6 +24,7 @@ import { Plugin } from "./plugin/plugin.js";
 import { toPlugin } from "./plugin/to-plugin.js";
 import "./plugin/index.js";
 import { analytics } from "./plugins/analytics/analytics.js";
+import { PolicyDeniedError, READ_ACTIONS, WRITE_ACTIONS } from "./plugins/files/policy.js";
 import { files } from "./plugins/files/plugin.js";
 import { genie } from "./plugins/genie/genie.js";
 import { lakebase } from "./plugins/lakebase/lakebase.js";
@@ -39,5 +40,5 @@ init_context();
 init_errors();
 
 //#endregion
-export { AppKitError, AuthenticationError, CacheManager, ConfigurationError, ConnectionError, ExecutionError, InitializationError, Plugin, RequestedClaimsPermissionSet, ResourceRegistry, ResourceType, ServerError, SeverityNumber, SpanStatusCode, TunnelError, ValidationError, analytics, appKitServingTypesPlugin, appKitTypesPlugin, createApp, createLakebasePool, extractServingEndpoints, files, findServerFile, generateDatabaseCredential, genie, getExecutionContext, getLakebaseOrmConfig, getLakebasePgConfig, getPluginManifest, getResourceRequirements, getUsernameWithApiLookup, getWorkspaceClient, isSQLTypeMarker, lakebase, server, serving, sql, toPlugin };
+export { AppKitError, AuthenticationError, CacheManager, ConfigurationError, ConnectionError, ExecutionError, InitializationError, Plugin, PolicyDeniedError, READ_ACTIONS, RequestedClaimsPermissionSet, ResourceRegistry, ResourceType, ServerError, SeverityNumber, SpanStatusCode, TunnelError, ValidationError, WRITE_ACTIONS, analytics, appKitServingTypesPlugin, appKitTypesPlugin, createApp, createLakebasePool, extractServingEndpoints, files, findServerFile, generateDatabaseCredential, genie, getExecutionContext, getLakebaseOrmConfig, getLakebasePgConfig, getPluginManifest, getResourceRequirements, getUsernameWithApiLookup, getWorkspaceClient, isSQLTypeMarker, lakebase, server, serving, sql, toPlugin };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["/**\n * @packageDocumentation\n *\n * Core library for building Databricks applications with type-safe SQL queries,\n * plugin architecture, and React integration.\n */\n\n// Types from shared\nexport type {\n  BasePluginConfig,\n  CacheConfig,\n  IAppRouter,\n  PluginData,\n  StreamExecutionSettings,\n} from \"shared\";\nexport { isSQLTypeMarker, sql } from \"shared\";\nexport { CacheManager } from \"./cache\";\nexport type {\n  DatabaseCredential,\n  GenerateDatabaseCredentialRequest,\n  LakebasePoolConfig,\n  RequestedClaims,\n  RequestedResource,\n} from \"./connectors/lakebase\";\n// Lakebase Autoscaling connector\nexport {\n  createLakebasePool,\n  generateDatabaseCredential,\n  getLakebaseOrmConfig,\n  getLakebasePgConfig,\n  getUsernameWithApiLookup,\n  getWorkspaceClient,\n  RequestedClaimsPermissionSet,\n} from \"./connectors/lakebase\";\nexport { getExecutionContext } from \"./context\";\nexport { createApp } from \"./core\";\n// Errors\nexport {\n  AppKitError,\n  AuthenticationError,\n  ConfigurationError,\n  ConnectionError,\n  ExecutionError,\n  InitializationError,\n  ServerError,\n  TunnelError,\n  ValidationError,\n} from \"./errors\";\n// Plugin authoring\nexport {\n  type ExecutionResult,\n  Plugin,\n  type ToPlugin,\n  toPlugin,\n} from \"./plugin\";\nexport { analytics, files, genie, lakebase, server, serving } from \"./plugins\";\nexport type {\n  EndpointConfig,\n  ServingEndpointEntry,\n  ServingEndpointRegistry,\n  ServingFactory,\n} from \"./plugins/serving/types\";\n// Registry types and utilities for plugin manifests\nexport type {\n  ConfigSchema,\n  PluginManifest,\n  ResourceEntry,\n  ResourceFieldEntry,\n  ResourcePermission,\n  ResourceRequirement,\n  ValidationResult,\n} from \"./registry\";\nexport {\n  getPluginManifest,\n  getResourceRequirements,\n  ResourceRegistry,\n  ResourceType,\n} from \"./registry\";\n// Telemetry (for advanced custom telemetry)\nexport {\n  type Counter,\n  type Histogram,\n  type ITelemetry,\n  SeverityNumber,\n  type Span,\n  SpanStatusCode,\n  type TelemetryConfig,\n} from \"./telemetry\";\nexport {\n  extractServingEndpoints,\n  findServerFile,\n} from \"./type-generator/serving/server-file-extractor\";\nexport { appKitServingTypesPlugin } from \"./type-generator/serving/vite-plugin\";\n// Vite plugin and type generation\nexport { appKitTypesPlugin } from \"./type-generator/vite-plugin\";\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAkCgD;aAa9B"}
+{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["/**\n * @packageDocumentation\n *\n * Core library for building Databricks applications with type-safe SQL queries,\n * plugin architecture, and React integration.\n */\n\n// Types from shared\nexport type {\n  BasePluginConfig,\n  CacheConfig,\n  IAppRouter,\n  PluginData,\n  StreamExecutionSettings,\n} from \"shared\";\nexport { isSQLTypeMarker, sql } from \"shared\";\nexport { CacheManager } from \"./cache\";\nexport type {\n  DatabaseCredential,\n  GenerateDatabaseCredentialRequest,\n  LakebasePoolConfig,\n  RequestedClaims,\n  RequestedResource,\n} from \"./connectors/lakebase\";\n// Lakebase Autoscaling connector\nexport {\n  createLakebasePool,\n  generateDatabaseCredential,\n  getLakebaseOrmConfig,\n  getLakebasePgConfig,\n  getUsernameWithApiLookup,\n  getWorkspaceClient,\n  RequestedClaimsPermissionSet,\n} from \"./connectors/lakebase\";\nexport { getExecutionContext } from \"./context\";\nexport { createApp } from \"./core\";\n// Errors\nexport {\n  AppKitError,\n  AuthenticationError,\n  ConfigurationError,\n  ConnectionError,\n  ExecutionError,\n  InitializationError,\n  ServerError,\n  TunnelError,\n  ValidationError,\n} from \"./errors\";\n// Plugin authoring\nexport {\n  type ExecutionResult,\n  Plugin,\n  type ToPlugin,\n  toPlugin,\n} from \"./plugin\";\nexport { analytics, files, genie, lakebase, server, serving } from \"./plugins\";\n// Files plugin types (for custom policy authoring)\nexport type {\n  FileAction,\n  FilePolicy,\n  FilePolicyUser,\n  FileResource,\n} from \"./plugins/files/policy\";\nexport {\n  PolicyDeniedError,\n  READ_ACTIONS,\n  WRITE_ACTIONS,\n} from \"./plugins/files/policy\";\nexport type {\n  EndpointConfig,\n  ServingEndpointEntry,\n  ServingEndpointRegistry,\n  ServingFactory,\n} from \"./plugins/serving/types\";\n// Registry types and utilities for plugin manifests\nexport type {\n  ConfigSchema,\n  PluginManifest,\n  ResourceEntry,\n  ResourceFieldEntry,\n  ResourcePermission,\n  ResourceRequirement,\n  ValidationResult,\n} from \"./registry\";\nexport {\n  getPluginManifest,\n  getResourceRequirements,\n  ResourceRegistry,\n  ResourceType,\n} from \"./registry\";\n// Telemetry (for advanced custom telemetry)\nexport {\n  type Counter,\n  type Histogram,\n  type ITelemetry,\n  SeverityNumber,\n  type Span,\n  SpanStatusCode,\n  type TelemetryConfig,\n} from \"./telemetry\";\nexport {\n  extractServingEndpoints,\n  findServerFile,\n} from \"./type-generator/serving/server-file-extractor\";\nexport { appKitServingTypesPlugin } from \"./type-generator/serving/vite-plugin\";\n// Vite plugin and type generation\nexport { appKitTypesPlugin } from \"./type-generator/vite-plugin\";\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAkCgD;aAa9B"}

package/dist/plugin/dev-reader.js.map

@@ -1 +1 @@
-{"version":3,"file":"dev-reader.js","names":[],"sources":["../../src/plugin/dev-reader.ts"],"sourcesContent":["import { randomUUID } from \"node:crypto\";\nimport type { TunnelConnection } from \"shared\";\nimport { isRemoteTunnelAllowedByEnv } from \"@/plugins/server/remote-tunnel/gate\";\nimport { TunnelError } from \"../errors\";\nimport { createLogger } from \"../logging/logger\";\n\nconst logger = createLogger(\"plugin:dev-reader\");\n\ntype TunnelConnectionGetter = (\n  req: import(\"express\").Request,\n) => TunnelConnection | null;\n\n/**\n * This class is used to read files from the local filesystem in dev mode\n * through the WebSocket tunnel.\n */\nexport class DevFileReader {\n  private static instance: DevFileReader | null = null;\n  private getTunnelForRequest: TunnelConnectionGetter | null = null;\n\n  private constructor() {}\n\n  static getInstance(): DevFileReader {\n    if (!DevFileReader.instance) {\n      DevFileReader.instance = new Proxy(new DevFileReader(), {\n        /**\n         * We proxy the reader to return a noop function if the remote server is disabled.\n         */\n        get(target, prop, receiver) {\n          if (isRemoteTunnelAllowedByEnv()) {\n            return Reflect.get(target, prop, receiver);\n          }\n\n          const value = Reflect.get(target, prop, receiver);\n\n          if (typeof value === \"function\") {\n            return function noop() {\n              logger.debug(\"Noop: %s (remote server disabled)\", String(prop));\n              return Promise.resolve(\"\");\n            };\n          }\n\n          return value;\n        },\n        set(target, prop, value, receiver) {\n          return Reflect.set(target, prop, value, receiver);\n        },\n      });\n    }\n\n    return DevFileReader.instance;\n  }\n\n  registerTunnelGetter(getter: TunnelConnectionGetter) {\n    this.getTunnelForRequest = getter;\n  }\n\n  async readFile(\n    filePath: string,\n    req: import(\"express\").Request,\n  ): Promise<string> {\n    if (!this.getTunnelForRequest) {\n      throw TunnelError.getterNotRegistered();\n    }\n    const tunnel = this.getTunnelForRequest(req);\n\n    if (!tunnel) {\n      throw TunnelError.noConnection();\n    }\n\n    const { ws, pendingFileReads } = tunnel;\n    const requestId = randomUUID();\n\n    return new Promise((resolve, reject) => {\n      const timeout = setTimeout(() => {\n        pendingFileReads.delete(requestId);\n        reject(new Error(`File read timeout: ${filePath}`));\n      }, 10000);\n\n      pendingFileReads.set(requestId, { resolve, reject, timeout });\n\n      ws.send(\n        JSON.stringify({\n          type: \"file:read\",\n          requestId,\n          path: filePath,\n        }),\n      );\n    });\n  }\n\n  async readdir(\n    dirPath: string,\n    req: import(\"express\").Request,\n  ): Promise<string[]> {\n    if (!this.getTunnelForRequest) {\n      throw TunnelError.getterNotRegistered();\n    }\n    const tunnel = this.getTunnelForRequest(req);\n\n    if (!tunnel) {\n      throw TunnelError.noConnection();\n    }\n\n    const { ws, pendingFileReads } = tunnel;\n    const requestId = randomUUID();\n\n    return new Promise((resolve, reject) => {\n      const timeout = setTimeout(() => {\n        pendingFileReads.delete(requestId);\n        reject(new Error(`Directory read timeout: ${dirPath}`));\n      }, 10000);\n\n      pendingFileReads.set(requestId, {\n        resolve: (data: string) => {\n          try {\n            const files = JSON.parse(data);\n            // Validate it's an array of strings\n            if (!Array.isArray(files)) {\n              reject(\n                new Error(\n                  \"Invalid directory listing format: expected array, got \" +\n                    typeof files,\n                ),\n              );\n              return;\n            }\n            if (!files.every((f) => typeof f === \"string\")) {\n              reject(\n                new Error(\n                  \"Invalid directory listing format: expected array of strings\",\n                ),\n              );\n              return;\n            }\n            resolve(files);\n          } catch (error) {\n            reject(\n              new Error(\n                `Failed to parse directory listing: ${(error as Error).message}`,\n              ),\n            );\n          }\n        },\n        reject,\n        timeout,\n      });\n\n      ws.send(\n        JSON.stringify({\n          type: \"dir:list\",\n          requestId,\n          path: dirPath,\n        }),\n      );\n    });\n  }\n}\n"],"mappings":";;;;;;;aAGwC;AAGxC,MAAM,SAAS,aAAa,oBAAoB;;;;;AAUhD,IAAa,gBAAb,MAAa,cAAc;CACzB,OAAe,WAAiC;CAChD,AAAQ,sBAAqD;CAE7D,AAAQ,cAAc;CAEtB,OAAO,cAA6B;AAClC,MAAI,CAAC,cAAc,SACjB,eAAc,WAAW,IAAI,MAAM,IAAI,eAAe,EAAE;GAItD,IAAI,QAAQ,MAAM,UAAU;AAC1B,QAAI,4BAA4B,CAC9B,QAAO,QAAQ,IAAI,QAAQ,MAAM,SAAS;IAG5C,MAAM,QAAQ,QAAQ,IAAI,QAAQ,MAAM,SAAS;AAEjD,QAAI,OAAO,UAAU,WACnB,QAAO,SAAS,OAAO;AACrB,YAAO,MAAM,qCAAqC,OAAO,KAAK,CAAC;AAC/D,YAAO,QAAQ,QAAQ,GAAG;;AAI9B,WAAO;;GAET,IAAI,QAAQ,MAAM,OAAO,UAAU;AACjC,WAAO,QAAQ,IAAI,QAAQ,MAAM,OAAO,SAAS;;GAEpD,CAAC;AAGJ,SAAO,cAAc;;CAGvB,qBAAqB,QAAgC;AACnD,OAAK,sBAAsB;;CAG7B,MAAM,SACJ,UACA,KACiB;AACjB,MAAI,CAAC,KAAK,oBACR,OAAM,YAAY,qBAAqB;EAEzC,MAAM,SAAS,KAAK,oBAAoB,IAAI;AAE5C,MAAI,CAAC,OACH,OAAM,YAAY,cAAc;EAGlC,MAAM,EAAE,IAAI,qBAAqB;EACjC,MAAM,YAAY,YAAY;AAE9B,SAAO,IAAI,SAAS,SAAS,WAAW;GACtC,MAAM,UAAU,iBAAiB;AAC/B,qBAAiB,OAAO,UAAU;AAClC,2BAAO,IAAI,MAAM,sBAAsB,WAAW,CAAC;MAClD,IAAM;AAET,oBAAiB,IAAI,WAAW;IAAE;IAAS;IAAQ;IAAS,CAAC;AAE7D,MAAG,KACD,KAAK,UAAU;IACb,MAAM;IACN;IACA,MAAM;IACP,CAAC,CACH;IACD;;CAGJ,MAAM,QACJ,SACA,KACmB;AACnB,MAAI,CAAC,KAAK,oBACR,OAAM,YAAY,qBAAqB;EAEzC,MAAM,SAAS,KAAK,oBAAoB,IAAI;AAE5C,MAAI,CAAC,OACH,OAAM,YAAY,cAAc;EAGlC,MAAM,EAAE,IAAI,qBAAqB;EACjC,MAAM,YAAY,YAAY;AAE9B,SAAO,IAAI,SAAS,SAAS,WAAW;GACtC,MAAM,UAAU,iBAAiB;AAC/B,qBAAiB,OAAO,UAAU;AAClC,2BAAO,IAAI,MAAM,2BAA2B,UAAU,CAAC;MACtD,IAAM;AAET,oBAAiB,IAAI,WAAW;IAC9B,UAAU,SAAiB;AACzB,SAAI;MACF,MAAM,QAAQ,KAAK,MAAM,KAAK;AAE9B,UAAI,CAAC,MAAM,QAAQ,MAAM,EAAE;AACzB,8BACE,IAAI,MACF,2DACE,OAAO,MACV,CACF;AACD;;AAEF,UAAI,CAAC,MAAM,OAAO,MAAM,OAAO,MAAM,SAAS,EAAE;AAC9C,8BACE,IAAI,MACF,8DACD,CACF;AACD;;AAEF,cAAQ,MAAM;cACP,OAAO;AACd,6BACE,IAAI,MACF,sCAAuC,MAAgB,UACxD,CACF;;;IAGL;IACA;IACD,CAAC;AAEF,MAAG,KACD,KAAK,UAAU;IACb,MAAM;IACN;IACA,MAAM;IACP,CAAC,CACH;IACD"}
+{"version":3,"file":"dev-reader.js","names":[],"sources":["../../src/plugin/dev-reader.ts"],"sourcesContent":["import { randomUUID } from \"node:crypto\";\nimport type { TunnelConnection } from \"shared\";\nimport { TunnelError } from \"../errors\";\nimport { createLogger } from \"../logging/logger\";\nimport { isRemoteTunnelAllowedByEnv } from \"../plugins/server/remote-tunnel/gate\";\n\nconst logger = createLogger(\"plugin:dev-reader\");\n\ntype TunnelConnectionGetter = (\n  req: import(\"express\").Request,\n) => TunnelConnection | null;\n\n/**\n * This class is used to read files from the local filesystem in dev mode\n * through the WebSocket tunnel.\n */\nexport class DevFileReader {\n  private static instance: DevFileReader | null = null;\n  private getTunnelForRequest: TunnelConnectionGetter | null = null;\n\n  private constructor() {}\n\n  static getInstance(): DevFileReader {\n    if (!DevFileReader.instance) {\n      DevFileReader.instance = new Proxy(new DevFileReader(), {\n        /**\n         * We proxy the reader to return a noop function if the remote server is disabled.\n         */\n        get(target, prop, receiver) {\n          if (isRemoteTunnelAllowedByEnv()) {\n            return Reflect.get(target, prop, receiver);\n          }\n\n          const value = Reflect.get(target, prop, receiver);\n\n          if (typeof value === \"function\") {\n            return function noop() {\n              logger.debug(\"Noop: %s (remote server disabled)\", String(prop));\n              return Promise.resolve(\"\");\n            };\n          }\n\n          return value;\n        },\n        set(target, prop, value, receiver) {\n          return Reflect.set(target, prop, value, receiver);\n        },\n      });\n    }\n\n    return DevFileReader.instance;\n  }\n\n  registerTunnelGetter(getter: TunnelConnectionGetter) {\n    this.getTunnelForRequest = getter;\n  }\n\n  async readFile(\n    filePath: string,\n    req: import(\"express\").Request,\n  ): Promise<string> {\n    if (!this.getTunnelForRequest) {\n      throw TunnelError.getterNotRegistered();\n    }\n    const tunnel = this.getTunnelForRequest(req);\n\n    if (!tunnel) {\n      throw TunnelError.noConnection();\n    }\n\n    const { ws, pendingFileReads } = tunnel;\n    const requestId = randomUUID();\n\n    return new Promise((resolve, reject) => {\n      const timeout = setTimeout(() => {\n        pendingFileReads.delete(requestId);\n        reject(new Error(`File read timeout: ${filePath}`));\n      }, 10000);\n\n      pendingFileReads.set(requestId, { resolve, reject, timeout });\n\n      ws.send(\n        JSON.stringify({\n          type: \"file:read\",\n          requestId,\n          path: filePath,\n        }),\n      );\n    });\n  }\n\n  async readdir(\n    dirPath: string,\n    req: import(\"express\").Request,\n  ): Promise<string[]> {\n    if (!this.getTunnelForRequest) {\n      throw TunnelError.getterNotRegistered();\n    }\n    const tunnel = this.getTunnelForRequest(req);\n\n    if (!tunnel) {\n      throw TunnelError.noConnection();\n    }\n\n    const { ws, pendingFileReads } = tunnel;\n    const requestId = randomUUID();\n\n    return new Promise((resolve, reject) => {\n      const timeout = setTimeout(() => {\n        pendingFileReads.delete(requestId);\n        reject(new Error(`Directory read timeout: ${dirPath}`));\n      }, 10000);\n\n      pendingFileReads.set(requestId, {\n        resolve: (data: string) => {\n          try {\n            const files = JSON.parse(data);\n            // Validate it's an array of strings\n            if (!Array.isArray(files)) {\n              reject(\n                new Error(\n                  \"Invalid directory listing format: expected array, got \" +\n                    typeof files,\n                ),\n              );\n              return;\n            }\n            if (!files.every((f) => typeof f === \"string\")) {\n              reject(\n                new Error(\n                  \"Invalid directory listing format: expected array of strings\",\n                ),\n              );\n              return;\n            }\n            resolve(files);\n          } catch (error) {\n            reject(\n              new Error(\n                `Failed to parse directory listing: ${(error as Error).message}`,\n              ),\n            );\n          }\n        },\n        reject,\n        timeout,\n      });\n\n      ws.send(\n        JSON.stringify({\n          type: \"dir:list\",\n          requestId,\n          path: dirPath,\n        }),\n      );\n    });\n  }\n}\n"],"mappings":";;;;;;;aAEwC;AAIxC,MAAM,SAAS,aAAa,oBAAoB;;;;;AAUhD,IAAa,gBAAb,MAAa,cAAc;CACzB,OAAe,WAAiC;CAChD,AAAQ,sBAAqD;CAE7D,AAAQ,cAAc;CAEtB,OAAO,cAA6B;AAClC,MAAI,CAAC,cAAc,SACjB,eAAc,WAAW,IAAI,MAAM,IAAI,eAAe,EAAE;GAItD,IAAI,QAAQ,MAAM,UAAU;AAC1B,QAAI,4BAA4B,CAC9B,QAAO,QAAQ,IAAI,QAAQ,MAAM,SAAS;IAG5C,MAAM,QAAQ,QAAQ,IAAI,QAAQ,MAAM,SAAS;AAEjD,QAAI,OAAO,UAAU,WACnB,QAAO,SAAS,OAAO;AACrB,YAAO,MAAM,qCAAqC,OAAO,KAAK,CAAC;AAC/D,YAAO,QAAQ,QAAQ,GAAG;;AAI9B,WAAO;;GAET,IAAI,QAAQ,MAAM,OAAO,UAAU;AACjC,WAAO,QAAQ,IAAI,QAAQ,MAAM,OAAO,SAAS;;GAEpD,CAAC;AAGJ,SAAO,cAAc;;CAGvB,qBAAqB,QAAgC;AACnD,OAAK,sBAAsB;;CAG7B,MAAM,SACJ,UACA,KACiB;AACjB,MAAI,CAAC,KAAK,oBACR,OAAM,YAAY,qBAAqB;EAEzC,MAAM,SAAS,KAAK,oBAAoB,IAAI;AAE5C,MAAI,CAAC,OACH,OAAM,YAAY,cAAc;EAGlC,MAAM,EAAE,IAAI,qBAAqB;EACjC,MAAM,YAAY,YAAY;AAE9B,SAAO,IAAI,SAAS,SAAS,WAAW;GACtC,MAAM,UAAU,iBAAiB;AAC/B,qBAAiB,OAAO,UAAU;AAClC,2BAAO,IAAI,MAAM,sBAAsB,WAAW,CAAC;MAClD,IAAM;AAET,oBAAiB,IAAI,WAAW;IAAE;IAAS;IAAQ;IAAS,CAAC;AAE7D,MAAG,KACD,KAAK,UAAU;IACb,MAAM;IACN;IACA,MAAM;IACP,CAAC,CACH;IACD;;CAGJ,MAAM,QACJ,SACA,KACmB;AACnB,MAAI,CAAC,KAAK,oBACR,OAAM,YAAY,qBAAqB;EAEzC,MAAM,SAAS,KAAK,oBAAoB,IAAI;AAE5C,MAAI,CAAC,OACH,OAAM,YAAY,cAAc;EAGlC,MAAM,EAAE,IAAI,qBAAqB;EACjC,MAAM,YAAY,YAAY;AAE9B,SAAO,IAAI,SAAS,SAAS,WAAW;GACtC,MAAM,UAAU,iBAAiB;AAC/B,qBAAiB,OAAO,UAAU;AAClC,2BAAO,IAAI,MAAM,2BAA2B,UAAU,CAAC;MACtD,IAAM;AAET,oBAAiB,IAAI,WAAW;IAC9B,UAAU,SAAiB;AACzB,SAAI;MACF,MAAM,QAAQ,KAAK,MAAM,KAAK;AAE9B,UAAI,CAAC,MAAM,QAAQ,MAAM,EAAE;AACzB,8BACE,IAAI,MACF,2DACE,OAAO,MACV,CACF;AACD;;AAEF,UAAI,CAAC,MAAM,OAAO,MAAM,OAAO,MAAM,SAAS,EAAE;AAC9C,8BACE,IAAI,MACF,8DACD,CACF;AACD;;AAEF,cAAQ,MAAM;cACP,OAAO;AACd,6BACE,IAAI,MACF,sCAAuC,MAAgB,UACxD,CACF;;;IAGL;IACA;IACD,CAAC;AAEF,MAAG,KACD,KAAK,UAAU;IACb,MAAM;IACN;IACA,MAAM;IACP,CAAC,CACH;IACD"}

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

@@ -4,6 +4,7 @@ import { Plugin } from "../../plugin/plugin.js";
 import "../../plugin/index.js";
 import { PluginManifest, ResourceRequirement } from "../../registry/types.js";
 import "../../registry/index.js";
+import { FilePolicy, FilePolicyUser } from "./policy.js";
 import { FilesExport, IFilesConfig, VolumeAPI, VolumeConfig } from "./types.js";
 
 //#region src/plugins/files/plugin.d.ts
@@ -28,21 +29,22 @@ declare class FilesPlugin extends Plugin {
    */
   static getResourceRequirements(config: IFilesConfig): ResourceRequirement[];
   /**
-   * Warns when a method is called without a user context (i.e. as service principal).
-   * OBO access via `asUser(req)` is strongly recommended.
+   * Extract user identity from the request.
+   * Falls back to `getCurrentUserId()` in development mode.
    */
-  private warnIfNoUserContext;
+  private _extractUser;
   /**
-   * Throws when a method is called without a user context (i.e. as service principal).
-   * OBO access via `asUser(req)` is enforced for now.
+   * Check the policy for a volume. No-op if no policy is configured.
+   * Throws `PolicyDeniedError` if denied.
    */
-  private throwIfNoUserContext;
-  constructor(config: IFilesConfig);
+  private _checkPolicy;
   /**
-   * Creates a VolumeAPI for a specific volume key.
-   * Each method warns if called outside a user context (service principal).
+   * HTTP-level wrapper around `_checkPolicy`.
+   * Extracts user (401 on failure), runs policy (403 on denial).
+   * Returns `true` if the request may proceed, `false` if a response was sent.
    */
-  protected createVolumeAPI(volumeKey: string): VolumeAPI;
+  private _enforcePolicy;
+  constructor(config: IFilesConfig);
   injectRoutes(router: IAppRouter): void;
   /**
    * Resolve `:volumeKey` from the request. Returns the connector and key,
@@ -59,6 +61,10 @@ declare class FilesPlugin extends Plugin {
    * Invalidate cached list entries for a directory after a write operation.
    * Uses the same cache-key format as `_handleList`: resolved path for
    * subdirectories, `"__root__"` for the volume root.
+   *
+   * Cache keys include `getCurrentUserId()` — must match the identity used
+   * by `this.execute()` in `_handleList`. Both run in service-principal
+   * context; wrapping either in `runInUserContext` would break invalidation.
    */
   private _invalidateListCache;
   private _handleApiError;
@@ -79,6 +85,19 @@ declare class FilesPlugin extends Plugin {
   private _handleUpload;
   private _handleMkdir;
   private _handleDelete;
+  /**
+   * Creates a VolumeAPI for a specific volume key.
+   *
+   * By default, enforces the volume's policy before each operation.
+   * Pass `bypassPolicy: true` to skip policy checks — useful for
+   * background jobs or migrations that should bypass user-facing policies.
+   *
+   * @security When `bypassPolicy` is `true`, no policy enforcement runs.
+   * Do not expose bypassed APIs to HTTP routes or end-user code paths.
+   */
+  protected createVolumeAPI(volumeKey: string, user: FilePolicyUser, options?: {
+    bypassPolicy?: boolean;
+  }): VolumeAPI;
   private inflightWrites;
   private trackWrite;
   shutdown(): Promise<void>;
@@ -86,13 +105,16 @@ declare class FilesPlugin extends Plugin {
    * Returns the programmatic API for the Files plugin.
    * Callable with a volume key to get a volume-scoped handle.
    *
+   * All operations execute as the service principal.
+   * Use policies to control per-user access.
+   *
    * @example
    * ```ts
-   * // OBO access (recommended)
-   * appKit.files("uploads").asUser(req).list()
-   *
-   * // Service principal access (logs a warning)
+   * // Service principal access
    * appKit.files("uploads").list()
+   *
+   * // With policy: pass user identity for access control
+   * appKit.files("uploads").asUser(req).list()
    * ```
    */
   exports(): FilesExport;
@@ -101,7 +123,16 @@ declare class FilesPlugin extends Plugin {
 /**
  * @internal
  */
-declare const files: ToPlugin<typeof FilesPlugin, IFilesConfig, string>;
+declare const files: ToPlugin<typeof FilesPlugin, IFilesConfig, string> & {
+  policy: {
+    readonly all: (...policies: FilePolicy[]) => FilePolicy;
+    readonly any: (...policies: FilePolicy[]) => FilePolicy;
+    readonly not: (p: FilePolicy) => FilePolicy;
+    readonly publicRead: () => FilePolicy;
+    readonly denyAll: () => FilePolicy;
+    readonly allowAll: () => FilePolicy;
+  };
+};
 //#endregion
 export { FilesPlugin, files };
 //# sourceMappingURL=plugin.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","names":[],"sources":["../../../src/plugins/files/plugin.ts"],"mappings":";;;;;;;;;cAoCa,WAAA,SAAoB,MAAA;EAC/B,IAAA;;SAGO,QAAA,EAAuB,cAAA;EAAA,iBACb,WAAA;EAAA,UACC,MAAA,EAAQ,YAAA;EAAA,QAElB,gBAAA;EAAA,QACA,aAAA;EAAA,QACA,UAAA;EAJkB;;;;;EAAA,OAWnB,eAAA,CAAgB,MAAA,EAAQ,YAAA,GAAe,MAAA,SAAe,YAAA;EAkEzC;;;;EAAA,OA3Cb,uBAAA,CAAwB,MAAA,EAAQ,YAAA,GAAe,mBAAA;EAu4BtC;;;;EAAA,QAj3BR,mBAAA;EA7DR;;;;EAAA,QA0EQ,oBAAA;cAQI,MAAA,EAAQ,YAAA;EA3EZ;;;;EAAA,UAgHE,eAAA,CAAgB,SAAA,WAAoB,SAAA;EAmD9C,YAAA,CAAa,MAAA,EAAQ,UAAA;EA1JyB;;;;EAAA,QAwRtC,cAAA;EAjQ8C;;;;EAAA,QAwR9C,YAAA;EAAA,QAQA,aAAA;EAhNE;;;;;EAAA,QAgOF,oBAAA;EAAA,QAiBA,eAAA;EAAA,QA8BA,gBAAA;EAAA,QAOM,WAAA;EAAA,QA+BA,WAAA;EAAA,QAoCA,eAAA;EAAA,QAWA,UAAA;EA9EA;;;;;EAAA,QA8FA,UAAA;EAAA,QA8EA,aAAA;EAAA,QAoCA,eAAA;EAAA,QAoCA,cAAA;EAAA,QAoCA,aAAA;EAAA,QA2GA,YAAA;EAAA,QA6CA,aAAA;EAAA,QA6CN,cAAA;EAAA,QAEA,UAAA;EAOF,QAAA,CAAA,GAAY,OAAA;EAgClB;;;;;;AAmCF;;;;;;;EAnCE,OAAA,CAAA,GAAW,WAAA;EA2BX,YAAA,CAAA,GAAgB,MAAA;AAAA;;;;cAQL,KAAA,EAAK,QAAA,QAAA,WAAA,EAAA,YAAA"}
+{"version":3,"file":"plugin.d.ts","names":[],"sources":["../../../src/plugins/files/plugin.ts"],"mappings":";;;;;;;;;;cA2Ca,WAAA,SAAoB,MAAA;EAC/B,IAAA;;SAGO,QAAA,EAAuB,cAAA;EAAA,iBACb,WAAA;EAAA,UACC,MAAA,EAAQ,YAAA;EAAA,QAElB,gBAAA;EAAA,QACA,aAAA;EAAA,QACA,UAAA;EAJkB;;;;;EAAA,OAWnB,eAAA,CAAgB,MAAA,EAAQ,YAAA,GAAe,MAAA,SAAe,YAAA;EAuIzC;;;;EAAA,OAhHb,uBAAA,CAAwB,MAAA,EAAQ,YAAA,GAAe,mBAAA;EAs9B3C;;;;EAAA,QAh8BH,YAAA;EA9DuB;;;;EAAA,QAiFjB,YAAA;EA3EI;;;;;EAAA,QA4GJ,cAAA;cAsCF,MAAA,EAAQ,YAAA;EA8CpB,YAAA,CAAa,MAAA,EAAQ,UAAA;EArLyB;;;;EAAA,QAmTtC,cAAA;EA5R8C;;;;EAAA,QAmT9C,YAAA;EAAA,QAQA,aAAA;EA3MI;;;;;;;;;EAAA,QA+NJ,oBAAA;EAAA,QAgBA,eAAA;EAAA,QAqCA,gBAAA;EAAA,QAOM,WAAA;EAAA,QA8BA,WAAA;EAAA,QAmCA,eAAA;EAAA,QAWA,UAAA;EAqIA;;;;;EAAA,QArHA,UAAA;EAAA,QAiFA,aAAA;EAAA,QAoCA,eAAA;EAAA,QAoCA,cAAA;EAAA,QAoCA,aAAA;EAAA,QAgHA,YAAA;EAAA,QA0CA,aAAA;EA4GN;;;;;;;;;;EAAA,UAxDE,eAAA,CACR,SAAA,UACA,IAAA,EAAM,cAAA,EACN,OAAA;IAAY,YAAA;EAAA,IACX,SAAA;EAAA,QAoDK,cAAA;EAAA,QAEA,UAAA;EAOF,QAAA,CAAA,GAAY,OAAA;EA6EF;;;;;;;;;;;;;;;;EA1ChB,OAAA,CAAA,GAAW,WAAA;EAkCX,YAAA,CAAA,GAAgB,MAAA;AAAA;;;;cAQL,KAAA,EAAK,QAAA,QAAA,WAAA,EAAA,YAAA;;gCAAA,UAAA"}

package/dist/plugins/files/plugin.js

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