@dbx-tools/appkit 0.6.48 → 0.6.49

package/README.md

@@ -38,6 +38,9 @@ Use this package when the friction is around bootstrapping and reuse:
 - AppKit does not own your local CLI flags, bundle validation output, or
   `app.yaml`; `config.resolveConfigValue()` gives setup scripts one resolution
   path across those sources.
+- AppKit's `asUser(req)` throws outside `NODE_ENV=development` when a request
+  carries no OBO token; `identity` makes falling back to the service principal a
+  configured, per-request decision instead of a `NODE_ENV` side effect.
 
 ## Create An Auto-Configured App
 
@@ -231,6 +234,58 @@ Pass a second argument to report progress on your own logger. The grants are
 skipped inside a Databricks App, and any failure is logged rather than thrown so
 a degraded cache never blocks startup.
 
+## Choose The Request Identity
+
+AppKit gives a plugin two identities: the ambient service context (the app's own
+service principal) and a per-request user context entered with `asUser(req)`,
+which authenticates on-behalf-of (OBO) using the token the Databricks front door
+forwards on `x-forwarded-access-token`. When that header is absent, AppKit's
+behaviour depends entirely on `NODE_ENV`:
+
+| `NODE_ENV`    | `asUser(req)` with no `x-forwarded-access-token`       |
+| ------------- | ------------------------------------------------------ |
+| `development` | logs a warning, silently runs as the service principal |
+| anything else | throws `AuthenticationError: Missing user token`       |
+
+That throw is right for an app behind the front door, where a missing token means
+something is broken. It is fatal for an app whose traffic legitimately arrives
+without one - a public tunnel where callers authenticate by email code
+([`@dbx-tools/cli-tunnel`](../../cli/tunnel)), or a bot channel that validates its
+own inbound JWT (`POST /api/teams/messages`). Those apps must not run with
+`NODE_ENV=development` just to get the fallback, since that flag also relaxes
+secure cookies and unlocks other dev-only escape hatches.
+
+`identity` is that decision, made explicit:
+
+```ts
+import { identity } from "@dbx-tools/appkit";
+
+const mode = identity.resolveIdentityMode(config.identity, "MY_APP_IDENTITY");
+
+// One call decides whether this request enters `asUser`.
+const scoped = identity.useServicePrincipal(mode, req) ? this : this.asUser(req);
+const rows = await scoped.executeQuery(sql);
+```
+
+| Mode                | Behaviour                                                                    |
+| ------------------- | ---------------------------------------------------------------------------- |
+| `user` (default)    | Always OBO. Per-user attribution and per-user Genie / Unity Catalog filters. |
+| `service-principal` | Always the app's own identity. Needs no OBO scopes and serves any caller.    |
+| `auto`              | OBO when the request carries a usable token, service principal otherwise.    |
+
+`auto` decides per REQUEST, not per boot, because one container can serve both
+doors at once - the tunnel gate and the platform front door share a port. A
+boot-time flag would have to be wrong for one of them. An unrecognized configured
+value throws a `ConfigurationError` rather than falling back, because a typo
+(`"obo"`, `"sp"`) would otherwise keep serving the very error the option was set
+to avoid.
+
+Running as the service principal does not change WHO the request belongs to. The
+caller still arrives on `x-forwarded-user` / `x-forwarded-email` (read them with
+`identity.requestUserId()` / `requestUserEmail()`), so memory threads, cache
+namespaces, and trace attribution stay per-user - only the Databricks credential
+is shared. `@dbx-tools/appkit-mastra` exposes this as its `genieIdentity` option.
+
 ## Modules
 
 | Module             | Responsibility                                                                             |
@@ -243,6 +298,7 @@ a degraded cache never blocks startup.
 | `databricks`       | App env detection and SDK context cancellation adapters.                                   |
 | `plugin`           | Typed AppKit plugin data, instance, and required-instance lookup.                          |
 | `provision`        | Cache schema provisioning helpers.                                                         |
+| `identity`         | OBO-vs-service-principal request identity: modes, resolution, and the forwarded headers.   |
 
 The shell-facing wrapper for auto-config is
 [`@dbx-tools/cli-appkit-env`](../../cli/appkit-env). Higher-level agent composition

package/index.ts

@@ -6,6 +6,7 @@ export * as appkit from "./src/appkit.ts";
 export * as config from "./src/config.ts";
 export * as createApp from "./src/create-app.ts";
 export * as databricks from "./src/databricks.ts";
+export * as identity from "./src/identity.ts";
 export * as lakebaseResolver from "./src/lakebase-resolver.ts";
 export * as pgaddress from "./src/pgaddress.ts";
 export * as plugin from "./src/plugin.ts";
@@ -15,6 +16,8 @@ export type { BundleValidateJson, ConfigFile, ConfigSource, ConfigMapValue, Reso
 export type { AutoConfigureMode, CreateAppConfig } from "./src/create-app.ts";
 export { MAX_TCP_PORT } from "./src/databricks.ts";
 export type { ContextLike } from "./src/databricks.ts";
+export { ACCESS_TOKEN_HEADER, USER_ID_HEADER, USER_EMAIL_HEADER, IDENTITY_MODES, DEFAULT_IDENTITY_MODE } from "./src/identity.ts";
+export type { IdentityMode, HeaderBearing } from "./src/identity.ts";
 export type { LakebaseResolverInputs, LakebaseConnection } from "./src/lakebase-resolver.ts";
 export { SSL_MODES } from "./src/pgaddress.ts";
 export type { SslMode, LakebaseConnectionInputs, ParsedAddress } from "./src/pgaddress.ts";

package/lib/index.d.ts

@@ -2,6 +2,7 @@ export * as appkit from "./src/appkit.ts";
 export * as config from "./src/config.ts";
 export * as createApp from "./src/create-app.ts";
 export * as databricks from "./src/databricks.ts";
+export * as identity from "./src/identity.ts";
 export * as lakebaseResolver from "./src/lakebase-resolver.ts";
 export * as pgaddress from "./src/pgaddress.ts";
 export * as plugin from "./src/plugin.ts";
@@ -11,6 +12,8 @@ export type { BundleValidateJson, ConfigFile, ConfigSource, ConfigMapValue, Reso
 export type { AutoConfigureMode, CreateAppConfig } from "./src/create-app.ts";
 export { MAX_TCP_PORT } from "./src/databricks.ts";
 export type { ContextLike } from "./src/databricks.ts";
+export { ACCESS_TOKEN_HEADER, USER_ID_HEADER, USER_EMAIL_HEADER, IDENTITY_MODES, DEFAULT_IDENTITY_MODE } from "./src/identity.ts";
+export type { IdentityMode, HeaderBearing } from "./src/identity.ts";
 export type { LakebaseResolverInputs, LakebaseConnection } from "./src/lakebase-resolver.ts";
 export { SSL_MODES } from "./src/pgaddress.ts";
 export type { SslMode, LakebaseConnectionInputs, ParsedAddress } from "./src/pgaddress.ts";

package/lib/index.js

@@ -5,10 +5,12 @@ export * as appkit from "./src/appkit.js";
 export * as config from "./src/config.js";
 export * as createApp from "./src/create-app.js";
 export * as databricks from "./src/databricks.js";
+export * as identity from "./src/identity.js";
 export * as lakebaseResolver from "./src/lakebase-resolver.js";
 export * as pgaddress from "./src/pgaddress.js";
 export * as plugin from "./src/plugin.js";
 export * as provision from "./src/provision.js";
 export { MAX_TCP_PORT } from "./src/databricks.js";
+export { ACCESS_TOKEN_HEADER, USER_ID_HEADER, USER_EMAIL_HEADER, IDENTITY_MODES, DEFAULT_IDENTITY_MODE } from "./src/identity.js";
 export { SSL_MODES } from "./src/pgaddress.js";
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSwyQ0FBMkM7QUFDM0MsbURBQW1EO0FBQ25ELHdFQUF3RTtBQUV4RSxPQUFPLEtBQUssTUFBTSxNQUFNLGlCQUFpQixDQUFDO0FBQzFDLE9BQU8sS0FBSyxNQUFNLE1BQU0saUJBQWlCLENBQUM7QUFDMUMsT0FBTyxLQUFLLFNBQVMsTUFBTSxxQkFBcUIsQ0FBQztBQUNqRCxPQUFPLEtBQUssVUFBVSxNQUFNLHFCQUFxQixDQUFDO0FBQ2xELE9BQU8sS0FBSyxnQkFBZ0IsTUFBTSw0QkFBNEIsQ0FBQztBQUMvRCxPQUFPLEtBQUssU0FBUyxNQUFNLG9CQUFvQixDQUFDO0FBQ2hELE9BQU8sS0FBSyxNQUFNLE1BQU0saUJBQWlCLENBQUM7QUFDMUMsT0FBTyxLQUFLLFNBQVMsTUFBTSxvQkFBb0IsQ0FBQztBQUloRCxPQUFPLEVBQUUsWUFBWSxFQUFFLE1BQU0scUJBQXFCLENBQUM7QUFHbkQsT0FBTyxFQUFFLFNBQVMsRUFBRSxNQUFNLG9CQUFvQixDQUFDIiwic291cmNlc0NvbnRlbnQiOlsiLy8gR0VORVJBVEVEIGJ5IHByb2plbiB3YXRjaCAtIERPIE5PVCBFRElULlxuLy8gUmVnZW5lcmF0ZWQgZnJvbSB0aGUgZXhwb3J0aW5nIG1vZHVsZXMgaW4gLi9zcmMuXG4vLyBIYW5kIGVkaXRzIGFyZSBvdmVyd3JpdHRlbiBvbiB0aGUgbmV4dCB3YXRjaDsgdGhpcyBmaWxlIGlzIHJlYWQtb25seS5cblxuZXhwb3J0ICogYXMgYXBwa2l0IGZyb20gXCIuL3NyYy9hcHBraXQudHNcIjtcbmV4cG9ydCAqIGFzIGNvbmZpZyBmcm9tIFwiLi9zcmMvY29uZmlnLnRzXCI7XG5leHBvcnQgKiBhcyBjcmVhdGVBcHAgZnJvbSBcIi4vc3JjL2NyZWF0ZS1hcHAudHNcIjtcbmV4cG9ydCAqIGFzIGRhdGFicmlja3MgZnJvbSBcIi4vc3JjL2RhdGFicmlja3MudHNcIjtcbmV4cG9ydCAqIGFzIGxha2ViYXNlUmVzb2x2ZXIgZnJvbSBcIi4vc3JjL2xha2ViYXNlLXJlc29sdmVyLnRzXCI7XG5leHBvcnQgKiBhcyBwZ2FkZHJlc3MgZnJvbSBcIi4vc3JjL3BnYWRkcmVzcy50c1wiO1xuZXhwb3J0ICogYXMgcGx1Z2luIGZyb20gXCIuL3NyYy9wbHVnaW4udHNcIjtcbmV4cG9ydCAqIGFzIHByb3Zpc2lvbiBmcm9tIFwiLi9zcmMvcHJvdmlzaW9uLnRzXCI7XG5leHBvcnQgdHlwZSB7IEV4ZWN1dGlvbkNvbnRleHRMaWtlLCBXb3Jrc3BhY2VDbGllbnRMaWtlIH0gZnJvbSBcIi4vc3JjL2FwcGtpdC50c1wiO1xuZXhwb3J0IHR5cGUgeyBCdW5kbGVWYWxpZGF0ZUpzb24sIENvbmZpZ0ZpbGUsIENvbmZpZ1NvdXJjZSwgQ29uZmlnTWFwVmFsdWUsIFJlc29sdmVDb25maWdWYWx1ZU9wdGlvbnMgfSBmcm9tIFwiLi9zcmMvY29uZmlnLnRzXCI7XG5leHBvcnQgdHlwZSB7IEF1dG9Db25maWd1cmVNb2RlLCBDcmVhdGVBcHBDb25maWcgfSBmcm9tIFwiLi9zcmMvY3JlYXRlLWFwcC50c1wiO1xuZXhwb3J0IHsgTUFYX1RDUF9QT1JUIH0gZnJvbSBcIi4vc3JjL2RhdGFicmlja3MudHNcIjtcbmV4cG9ydCB0eXBlIHsgQ29udGV4dExpa2UgfSBmcm9tIFwiLi9zcmMvZGF0YWJyaWNrcy50c1wiO1xuZXhwb3J0IHR5cGUgeyBMYWtlYmFzZVJlc29sdmVySW5wdXRzLCBMYWtlYmFzZUNvbm5lY3Rpb24gfSBmcm9tIFwiLi9zcmMvbGFrZWJhc2UtcmVzb2x2ZXIudHNcIjtcbmV4cG9ydCB7IFNTTF9NT0RFUyB9IGZyb20gXCIuL3NyYy9wZ2FkZHJlc3MudHNcIjtcbmV4cG9ydCB0eXBlIHsgU3NsTW9kZSwgTGFrZWJhc2VDb25uZWN0aW9uSW5wdXRzLCBQYXJzZWRBZGRyZXNzIH0gZnJvbSBcIi4vc3JjL3BnYWRkcmVzcy50c1wiO1xuZXhwb3J0IHR5cGUgeyBQbHVnaW5Db250ZXh0TGlrZSB9IGZyb20gXCIuL3NyYy9wbHVnaW4udHNcIjtcbiJdfQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSwyQ0FBMkM7QUFDM0MsbURBQW1EO0FBQ25ELHdFQUF3RTtBQUV4RSxPQUFPLEtBQUssTUFBTSxNQUFNLGlCQUFpQixDQUFDO0FBQzFDLE9BQU8sS0FBSyxNQUFNLE1BQU0saUJBQWlCLENBQUM7QUFDMUMsT0FBTyxLQUFLLFNBQVMsTUFBTSxxQkFBcUIsQ0FBQztBQUNqRCxPQUFPLEtBQUssVUFBVSxNQUFNLHFCQUFxQixDQUFDO0FBQ2xELE9BQU8sS0FBSyxRQUFRLE1BQU0sbUJBQW1CLENBQUM7QUFDOUMsT0FBTyxLQUFLLGdCQUFnQixNQUFNLDRCQUE0QixDQUFDO0FBQy9ELE9BQU8sS0FBSyxTQUFTLE1BQU0sb0JBQW9CLENBQUM7QUFDaEQsT0FBTyxLQUFLLE1BQU0sTUFBTSxpQkFBaUIsQ0FBQztBQUMxQyxPQUFPLEtBQUssU0FBUyxNQUFNLG9CQUFvQixDQUFDO0FBSWhELE9BQU8sRUFBRSxZQUFZLEVBQUUsTUFBTSxxQkFBcUIsQ0FBQztBQUVuRCxPQUFPLEVBQUUsbUJBQW1CLEVBQUUsY0FBYyxFQUFFLGlCQUFpQixFQUFFLGNBQWMsRUFBRSxxQkFBcUIsRUFBRSxNQUFNLG1CQUFtQixDQUFDO0FBR2xJLE9BQU8sRUFBRSxTQUFTLEVBQUUsTUFBTSxvQkFBb0IsQ0FBQyIsInNvdXJjZXNDb250ZW50IjpbIi8vIEdFTkVSQVRFRCBieSBwcm9qZW4gd2F0Y2ggLSBETyBOT1QgRURJVC5cbi8vIFJlZ2VuZXJhdGVkIGZyb20gdGhlIGV4cG9ydGluZyBtb2R1bGVzIGluIC4vc3JjLlxuLy8gSGFuZCBlZGl0cyBhcmUgb3ZlcndyaXR0ZW4gb24gdGhlIG5leHQgd2F0Y2g7IHRoaXMgZmlsZSBpcyByZWFkLW9ubHkuXG5cbmV4cG9ydCAqIGFzIGFwcGtpdCBmcm9tIFwiLi9zcmMvYXBwa2l0LnRzXCI7XG5leHBvcnQgKiBhcyBjb25maWcgZnJvbSBcIi4vc3JjL2NvbmZpZy50c1wiO1xuZXhwb3J0ICogYXMgY3JlYXRlQXBwIGZyb20gXCIuL3NyYy9jcmVhdGUtYXBwLnRzXCI7XG5leHBvcnQgKiBhcyBkYXRhYnJpY2tzIGZyb20gXCIuL3NyYy9kYXRhYnJpY2tzLnRzXCI7XG5leHBvcnQgKiBhcyBpZGVudGl0eSBmcm9tIFwiLi9zcmMvaWRlbnRpdHkudHNcIjtcbmV4cG9ydCAqIGFzIGxha2ViYXNlUmVzb2x2ZXIgZnJvbSBcIi4vc3JjL2xha2ViYXNlLXJlc29sdmVyLnRzXCI7XG5leHBvcnQgKiBhcyBwZ2FkZHJlc3MgZnJvbSBcIi4vc3JjL3BnYWRkcmVzcy50c1wiO1xuZXhwb3J0ICogYXMgcGx1Z2luIGZyb20gXCIuL3NyYy9wbHVnaW4udHNcIjtcbmV4cG9ydCAqIGFzIHByb3Zpc2lvbiBmcm9tIFwiLi9zcmMvcHJvdmlzaW9uLnRzXCI7XG5leHBvcnQgdHlwZSB7IEV4ZWN1dGlvbkNvbnRleHRMaWtlLCBXb3Jrc3BhY2VDbGllbnRMaWtlIH0gZnJvbSBcIi4vc3JjL2FwcGtpdC50c1wiO1xuZXhwb3J0IHR5cGUgeyBCdW5kbGVWYWxpZGF0ZUpzb24sIENvbmZpZ0ZpbGUsIENvbmZpZ1NvdXJjZSwgQ29uZmlnTWFwVmFsdWUsIFJlc29sdmVDb25maWdWYWx1ZU9wdGlvbnMgfSBmcm9tIFwiLi9zcmMvY29uZmlnLnRzXCI7XG5leHBvcnQgdHlwZSB7IEF1dG9Db25maWd1cmVNb2RlLCBDcmVhdGVBcHBDb25maWcgfSBmcm9tIFwiLi9zcmMvY3JlYXRlLWFwcC50c1wiO1xuZXhwb3J0IHsgTUFYX1RDUF9QT1JUIH0gZnJvbSBcIi4vc3JjL2RhdGFicmlja3MudHNcIjtcbmV4cG9ydCB0eXBlIHsgQ29udGV4dExpa2UgfSBmcm9tIFwiLi9zcmMvZGF0YWJyaWNrcy50c1wiO1xuZXhwb3J0IHsgQUNDRVNTX1RPS0VOX0hFQURFUiwgVVNFUl9JRF9IRUFERVIsIFVTRVJfRU1BSUxfSEVBREVSLCBJREVOVElUWV9NT0RFUywgREVGQVVMVF9JREVOVElUWV9NT0RFIH0gZnJvbSBcIi4vc3JjL2lkZW50aXR5LnRzXCI7XG5leHBvcnQgdHlwZSB7IElkZW50aXR5TW9kZSwgSGVhZGVyQmVhcmluZyB9IGZyb20gXCIuL3NyYy9pZGVudGl0eS50c1wiO1xuZXhwb3J0IHR5cGUgeyBMYWtlYmFzZVJlc29sdmVySW5wdXRzLCBMYWtlYmFzZUNvbm5lY3Rpb24gfSBmcm9tIFwiLi9zcmMvbGFrZWJhc2UtcmVzb2x2ZXIudHNcIjtcbmV4cG9ydCB7IFNTTF9NT0RFUyB9IGZyb20gXCIuL3NyYy9wZ2FkZHJlc3MudHNcIjtcbmV4cG9ydCB0eXBlIHsgU3NsTW9kZSwgTGFrZWJhc2VDb25uZWN0aW9uSW5wdXRzLCBQYXJzZWRBZGRyZXNzIH0gZnJvbSBcIi4vc3JjL3BnYWRkcmVzcy50c1wiO1xuZXhwb3J0IHR5cGUgeyBQbHVnaW5Db250ZXh0TGlrZSB9IGZyb20gXCIuL3NyYy9wbHVnaW4udHNcIjtcbiJdfQ==

package/lib/src/identity.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Which Databricks identity a request's workspace calls run as.
+ *
+ * AppKit gives a plugin two identities: the ambient SERVICE context (the app's
+ * own service principal) and a per-request USER context entered with
+ * `asUser(req)`, which authenticates as the caller on-behalf-of (OBO). The
+ * choice is one call, so the whole decision is "do we enter `asUser` for this
+ * request".
+ *
+ * `asUser(req)` needs the OBO token the platform front door forwards on
+ * {@link ACCESS_TOKEN_HEADER}. Measured against the installed AppKit, its
+ * behavior when that header is absent depends ENTIRELY on `NODE_ENV`:
+ *
+ * | `NODE_ENV`    | no `x-forwarded-access-token`                        |
+ * | ------------- | ---------------------------------------------------- |
+ * | `development` | logs a warning, silently runs as the service principal |
+ * | anything else | throws `AuthenticationError: Missing user token`      |
+ *
+ * That production throw is correct for an app behind the Databricks front door,
+ * where a missing token means something is wrong. It is fatal for an app whose
+ * traffic legitimately arrives WITHOUT one:
+ *
+ *   - a public tunnel (`@dbx-tools/cli-tunnel`), where callers authenticate by
+ *     email OTP and no OBO token exists to forward - the gate can prove WHO the
+ *     caller is, but it cannot mint a Databricks credential for them;
+ *   - any reverse proxy, webhook, or bot channel (`POST /api/teams/messages`)
+ *     that authenticates its own way.
+ *
+ * Such an app must not run with `NODE_ENV=development` just to get the fallback:
+ * that flag also relaxes secure cookies, AppKit's own dev affordances, and
+ * `allowUnauthenticated` escape hatches. Hence {@link IdentityMode}:
+ *
+ *   - `"user"` - always OBO. Per-user attribution and per-user Genie / Unity
+ *     Catalog row filters. Correct when every caller is a workspace member.
+ *   - `"service-principal"` - always the app's own identity. Needs no OBO
+ *     scopes and works for any caller, at the cost of per-user data scoping.
+ *   - `"auto"` - OBO when the request actually carries a usable OBO token,
+ *     the service principal otherwise. One deployment then serves BOTH doors
+ *     correctly: front-door requests keep full per-user scoping, while tunnel /
+ *     webhook requests degrade to the service principal instead of 500ing.
+ *
+ * `"auto"` decides per REQUEST, not per boot, because a single container serves
+ * both doors at once - the tunnel gate and the platform front door share a port
+ * (see `@dbx-tools/cli-tunnel`). A boot-time flag would have to be wrong for one
+ * of them.
+ *
+ * What the service principal does NOT change is WHO the request belongs to. The
+ * caller's identity still arrives on {@link USER_ID_HEADER} /
+ * {@link USER_EMAIL_HEADER}, so memory threads, cache namespaces, and trace
+ * attribution stay per-user. Only the Databricks credential is shared.
+ *
+ * @module
+ */
+import { type EnvKey } from "@dbx-tools/shared-core";
+/**
+ * Header the Databricks Apps front door forwards the caller's OBO token on.
+ * Its presence is what makes `asUser(req)` viable, so it is the signal
+ * {@link useServicePrincipal} reads in `"auto"` mode.
+ *
+ * Re-exported from `@dbx-tools/shared-core`'s `token` module (which reads the
+ * same header to decode OAuth scopes) rather than re-spelled, so the name for
+ * this wire contract exists once.
+ */
+export declare const ACCESS_TOKEN_HEADER = "x-forwarded-access-token";
+/** Header the Databricks Apps front door forwards the caller's user id on. */
+export declare const USER_ID_HEADER = "x-forwarded-user";
+/** Header the Databricks Apps front door forwards the caller's email on. */
+export declare const USER_EMAIL_HEADER = "x-forwarded-email";
+/** Identity a request's Databricks calls run as. See the module docs. */
+export type IdentityMode = "user" | "service-principal" | "auto";
+/** Every accepted {@link IdentityMode}, in the order docs and schemas list them. */
+export declare const IDENTITY_MODES: readonly IdentityMode[];
+/**
+ * Default mode. `"user"` keeps OBO the only identity unless an app opts in, so
+ * adopting this option can never silently widen an existing app's data access.
+ */
+export declare const DEFAULT_IDENTITY_MODE: IdentityMode;
+/** The subset of `express.Request` this module reads - one header lookup. */
+export interface HeaderBearing {
+    header(name: string): string | undefined;
+}
+/**
+ * Resolve a configured mode: explicit config value, then the first non-empty
+ * variable among `envKeys`, then {@link DEFAULT_IDENTITY_MODE}.
+ *
+ * An unrecognized value throws rather than falling back. Falling back would
+ * silently keep serving OBO - and the production `AuthenticationError` it
+ * produces - to exactly the callers the option was set to accommodate, and a
+ * typo (`"obo"`, `"sp"`) is the likeliest way to get one.
+ */
+export declare function resolveIdentityMode(configured: string | undefined, envKeys: EnvKey, field?: string): IdentityMode;
+/**
+ * The OBO token on `req`, or `undefined`. Read through the same trim as every
+ * other header, so a header present-but-blank (which some proxies emit for an
+ * unset upstream value) counts as absent rather than as a token that fails at
+ * the first Databricks call.
+ */
+export declare function requestAccessToken(req: HeaderBearing | undefined): string | undefined;
+/** The forwarded user id on `req`, or `undefined`. */
+export declare function requestUserId(req: HeaderBearing | undefined): string | undefined;
+/** The forwarded user email on `req`, or `undefined`. */
+export declare function requestUserEmail(req: HeaderBearing | undefined): string | undefined;
+/**
+ * Whether `req` should run its Databricks calls as the app service principal
+ * rather than OBO.
+ *
+ * - `"service-principal"` -> always `true`.
+ * - `"user"` -> always `false`, even with no token. The mode is an explicit
+ *   assertion that every caller is OBO-capable, so a missing token is a real
+ *   error and must surface as AppKit's `AuthenticationError` rather than being
+ *   quietly downgraded to shared data access.
+ * - `"auto"` -> `true` only when the request carries no usable OBO token.
+ *
+ * A request AppKit will not accept for OBO anyway (no token) can never be
+ * served by entering `asUser`, so in `"auto"` mode the token check is the whole
+ * decision: it is the same condition AppKit itself branches on, just resolved
+ * before it can throw.
+ */
+export declare function useServicePrincipal(mode: IdentityMode, req?: HeaderBearing): boolean;

package/lib/src/identity.js

@@ -0,0 +1,137 @@
+/**
+ * Which Databricks identity a request's workspace calls run as.
+ *
+ * AppKit gives a plugin two identities: the ambient SERVICE context (the app's
+ * own service principal) and a per-request USER context entered with
+ * `asUser(req)`, which authenticates as the caller on-behalf-of (OBO). The
+ * choice is one call, so the whole decision is "do we enter `asUser` for this
+ * request".
+ *
+ * `asUser(req)` needs the OBO token the platform front door forwards on
+ * {@link ACCESS_TOKEN_HEADER}. Measured against the installed AppKit, its
+ * behavior when that header is absent depends ENTIRELY on `NODE_ENV`:
+ *
+ * | `NODE_ENV`    | no `x-forwarded-access-token`                        |
+ * | ------------- | ---------------------------------------------------- |
+ * | `development` | logs a warning, silently runs as the service principal |
+ * | anything else | throws `AuthenticationError: Missing user token`      |
+ *
+ * That production throw is correct for an app behind the Databricks front door,
+ * where a missing token means something is wrong. It is fatal for an app whose
+ * traffic legitimately arrives WITHOUT one:
+ *
+ *   - a public tunnel (`@dbx-tools/cli-tunnel`), where callers authenticate by
+ *     email OTP and no OBO token exists to forward - the gate can prove WHO the
+ *     caller is, but it cannot mint a Databricks credential for them;
+ *   - any reverse proxy, webhook, or bot channel (`POST /api/teams/messages`)
+ *     that authenticates its own way.
+ *
+ * Such an app must not run with `NODE_ENV=development` just to get the fallback:
+ * that flag also relaxes secure cookies, AppKit's own dev affordances, and
+ * `allowUnauthenticated` escape hatches. Hence {@link IdentityMode}:
+ *
+ *   - `"user"` - always OBO. Per-user attribution and per-user Genie / Unity
+ *     Catalog row filters. Correct when every caller is a workspace member.
+ *   - `"service-principal"` - always the app's own identity. Needs no OBO
+ *     scopes and works for any caller, at the cost of per-user data scoping.
+ *   - `"auto"` - OBO when the request actually carries a usable OBO token,
+ *     the service principal otherwise. One deployment then serves BOTH doors
+ *     correctly: front-door requests keep full per-user scoping, while tunnel /
+ *     webhook requests degrade to the service principal instead of 500ing.
+ *
+ * `"auto"` decides per REQUEST, not per boot, because a single container serves
+ * both doors at once - the tunnel gate and the platform front door share a port
+ * (see `@dbx-tools/cli-tunnel`). A boot-time flag would have to be wrong for one
+ * of them.
+ *
+ * What the service principal does NOT change is WHO the request belongs to. The
+ * caller's identity still arrives on {@link USER_ID_HEADER} /
+ * {@link USER_EMAIL_HEADER}, so memory threads, cache namespaces, and trace
+ * attribution stay per-user. Only the Databricks credential is shared.
+ *
+ * @module
+ */
+import { ConfigurationError } from "@databricks/appkit";
+import { env, string, token } from "@dbx-tools/shared-core";
+/**
+ * Header the Databricks Apps front door forwards the caller's OBO token on.
+ * Its presence is what makes `asUser(req)` viable, so it is the signal
+ * {@link useServicePrincipal} reads in `"auto"` mode.
+ *
+ * Re-exported from `@dbx-tools/shared-core`'s `token` module (which reads the
+ * same header to decode OAuth scopes) rather than re-spelled, so the name for
+ * this wire contract exists once.
+ */
+export const ACCESS_TOKEN_HEADER = token.ACCESS_TOKEN_HEADER;
+/** Header the Databricks Apps front door forwards the caller's user id on. */
+export const USER_ID_HEADER = token.USER_ID_HEADER;
+/** Header the Databricks Apps front door forwards the caller's email on. */
+export const USER_EMAIL_HEADER = token.USER_EMAIL_HEADER;
+/** Every accepted {@link IdentityMode}, in the order docs and schemas list them. */
+export const IDENTITY_MODES = ["user", "service-principal", "auto"];
+/**
+ * Default mode. `"user"` keeps OBO the only identity unless an app opts in, so
+ * adopting this option can never silently widen an existing app's data access.
+ */
+export const DEFAULT_IDENTITY_MODE = "user";
+/**
+ * Resolve a configured mode: explicit config value, then the first non-empty
+ * variable among `envKeys`, then {@link DEFAULT_IDENTITY_MODE}.
+ *
+ * An unrecognized value throws rather than falling back. Falling back would
+ * silently keep serving OBO - and the production `AuthenticationError` it
+ * produces - to exactly the callers the option was set to accommodate, and a
+ * typo (`"obo"`, `"sp"`) is the likeliest way to get one.
+ */
+export function resolveIdentityMode(configured, envKeys, field = "identity") {
+    const raw = env.string(configured, envKeys);
+    if (raw === null)
+        return DEFAULT_IDENTITY_MODE;
+    const mode = raw.toLowerCase();
+    if (!IDENTITY_MODES.includes(mode)) {
+        const names = typeof envKeys === "string" ? envKeys : envKeys.join(" / ");
+        throw new ConfigurationError(`${field} must be one of ${IDENTITY_MODES.join(" | ")} (env: ${names})`, { context: { field, envVar: names, received: raw } });
+    }
+    return mode;
+}
+/**
+ * The OBO token on `req`, or `undefined`. Read through the same trim as every
+ * other header, so a header present-but-blank (which some proxies emit for an
+ * unset upstream value) counts as absent rather than as a token that fails at
+ * the first Databricks call.
+ */
+export function requestAccessToken(req) {
+    return string.trimToNull(req?.header(ACCESS_TOKEN_HEADER)) ?? undefined;
+}
+/** The forwarded user id on `req`, or `undefined`. */
+export function requestUserId(req) {
+    return string.trimToNull(req?.header(USER_ID_HEADER)) ?? undefined;
+}
+/** The forwarded user email on `req`, or `undefined`. */
+export function requestUserEmail(req) {
+    return string.trimToNull(req?.header(USER_EMAIL_HEADER)) ?? undefined;
+}
+/**
+ * Whether `req` should run its Databricks calls as the app service principal
+ * rather than OBO.
+ *
+ * - `"service-principal"` -> always `true`.
+ * - `"user"` -> always `false`, even with no token. The mode is an explicit
+ *   assertion that every caller is OBO-capable, so a missing token is a real
+ *   error and must surface as AppKit's `AuthenticationError` rather than being
+ *   quietly downgraded to shared data access.
+ * - `"auto"` -> `true` only when the request carries no usable OBO token.
+ *
+ * A request AppKit will not accept for OBO anyway (no token) can never be
+ * served by entering `asUser`, so in `"auto"` mode the token check is the whole
+ * decision: it is the same condition AppKit itself branches on, just resolved
+ * before it can throw.
+ */
+export function useServicePrincipal(mode, req) {
+    if (mode === "service-principal")
+        return true;
+    if (mode === "user")
+        return false;
+    return requestAccessToken(req) === undefined;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaWRlbnRpdHkuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvaWRlbnRpdHkudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUE7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7R0FvREc7QUFFSCxPQUFPLEVBQUUsa0JBQWtCLEVBQUUsTUFBTSxvQkFBb0IsQ0FBQztBQUN4RCxPQUFPLEVBQUUsR0FBRyxFQUFFLE1BQU0sRUFBRSxLQUFLLEVBQWUsTUFBTSx3QkFBd0IsQ0FBQztBQUV6RTs7Ozs7Ozs7R0FRRztBQUNILE1BQU0sQ0FBQyxNQUFNLG1CQUFtQixHQUFHLEtBQUssQ0FBQyxtQkFBbUIsQ0FBQztBQUU3RCw4RUFBOEU7QUFDOUUsTUFBTSxDQUFDLE1BQU0sY0FBYyxHQUFHLEtBQUssQ0FBQyxjQUFjLENBQUM7QUFFbkQsNEVBQTRFO0FBQzVFLE1BQU0sQ0FBQyxNQUFNLGlCQUFpQixHQUFHLEtBQUssQ0FBQyxpQkFBaUIsQ0FBQztBQUt6RCxvRkFBb0Y7QUFDcEYsTUFBTSxDQUFDLE1BQU0sY0FBYyxHQUE0QixDQUFDLE1BQU0sRUFBRSxtQkFBbUIsRUFBRSxNQUFNLENBQUMsQ0FBQztBQUU3Rjs7O0dBR0c7QUFDSCxNQUFNLENBQUMsTUFBTSxxQkFBcUIsR0FBaUIsTUFBTSxDQUFDO0FBTzFEOzs7Ozs7OztHQVFHO0FBQ0gsTUFBTSxVQUFVLG1CQUFtQixDQUNqQyxVQUE4QixFQUM5QixPQUFlLEVBQ2YsS0FBSyxHQUFHLFVBQVU7SUFFbEIsTUFBTSxHQUFHLEdBQUcsR0FBRyxDQUFDLE1BQU0sQ0FBQyxVQUFVLEVBQUUsT0FBTyxDQUFDLENBQUM7SUFDNUMsSUFBSSxHQUFHLEtBQUssSUFBSTtRQUFFLE9BQU8scUJBQXFCLENBQUM7SUFDL0MsTUFBTSxJQUFJLEdBQUcsR0FBRyxDQUFDLFdBQVcsRUFBa0IsQ0FBQztJQUMvQyxJQUFJLENBQUMsY0FBYyxDQUFDLFFBQVEsQ0FBQyxJQUFJLENBQUMsRUFBRSxDQUFDO1FBQ25DLE1BQU0sS0FBSyxHQUFHLE9BQU8sT0FBTyxLQUFLLFFBQVEsQ0FBQyxDQUFDLENBQUMsT0FBTyxDQUFDLENBQUMsQ0FBQyxPQUFPLENBQUMsSUFBSSxDQUFDLEtBQUssQ0FBQyxDQUFDO1FBQzFFLE1BQU0sSUFBSSxrQkFBa0IsQ0FDMUIsR0FBRyxLQUFLLG1CQUFtQixjQUFjLENBQUMsSUFBSSxDQUFDLEtBQUssQ0FBQyxVQUFVLEtBQUssR0FBRyxFQUN2RSxFQUFFLE9BQU8sRUFBRSxFQUFFLEtBQUssRUFBRSxNQUFNLEVBQUUsS0FBSyxFQUFFLFFBQVEsRUFBRSxHQUFHLEVBQUUsRUFBRSxDQUNyRCxDQUFDO0lBQ0osQ0FBQztJQUNELE9BQU8sSUFBSSxDQUFDO0FBQ2QsQ0FBQztBQUVEOzs7OztHQUtHO0FBQ0gsTUFBTSxVQUFVLGtCQUFrQixDQUFDLEdBQThCO0lBQy9ELE9BQU8sTUFBTSxDQUFDLFVBQVUsQ0FBQyxHQUFHLEVBQUUsTUFBTSxDQUFDLG1CQUFtQixDQUFDLENBQUMsSUFBSSxTQUFTLENBQUM7QUFDMUUsQ0FBQztBQUVELHNEQUFzRDtBQUN0RCxNQUFNLFVBQVUsYUFBYSxDQUFDLEdBQThCO0lBQzFELE9BQU8sTUFBTSxDQUFDLFVBQVUsQ0FBQyxHQUFHLEVBQUUsTUFBTSxDQUFDLGNBQWMsQ0FBQyxDQUFDLElBQUksU0FBUyxDQUFDO0FBQ3JFLENBQUM7QUFFRCx5REFBeUQ7QUFDekQsTUFBTSxVQUFVLGdCQUFnQixDQUFDLEdBQThCO0lBQzdELE9BQU8sTUFBTSxDQUFDLFVBQVUsQ0FBQyxHQUFHLEVBQUUsTUFBTSxDQUFDLGlCQUFpQixDQUFDLENBQUMsSUFBSSxTQUFTLENBQUM7QUFDeEUsQ0FBQztBQUVEOzs7Ozs7Ozs7Ozs7Ozs7R0FlRztBQUNILE1BQU0sVUFBVSxtQkFBbUIsQ0FBQyxJQUFrQixFQUFFLEdBQW1CO0lBQ3pFLElBQUksSUFBSSxLQUFLLG1CQUFtQjtRQUFFLE9BQU8sSUFBSSxDQUFDO0lBQzlDLElBQUksSUFBSSxLQUFLLE1BQU07UUFBRSxPQUFPLEtBQUssQ0FBQztJQUNsQyxPQUFPLGtCQUFrQixDQUFDLEdBQUcsQ0FBQyxLQUFLLFNBQVMsQ0FBQztBQUMvQyxDQUFDIiwic291cmNlc0NvbnRlbnQiOlsiLyoqXG4gKiBXaGljaCBEYXRhYnJpY2tzIGlkZW50aXR5IGEgcmVxdWVzdCdzIHdvcmtzcGFjZSBjYWxscyBydW4gYXMuXG4gKlxuICogQXBwS2l0IGdpdmVzIGEgcGx1Z2luIHR3byBpZGVudGl0aWVzOiB0aGUgYW1iaWVudCBTRVJWSUNFIGNvbnRleHQgKHRoZSBhcHAnc1xuICogb3duIHNlcnZpY2UgcHJpbmNpcGFsKSBhbmQgYSBwZXItcmVxdWVzdCBVU0VSIGNvbnRleHQgZW50ZXJlZCB3aXRoXG4gKiBgYXNVc2VyKHJlcSlgLCB3aGljaCBhdXRoZW50aWNhdGVzIGFzIHRoZSBjYWxsZXIgb24tYmVoYWxmLW9mIChPQk8pLiBUaGVcbiAqIGNob2ljZSBpcyBvbmUgY2FsbCwgc28gdGhlIHdob2xlIGRlY2lzaW9uIGlzIFwiZG8gd2UgZW50ZXIgYGFzVXNlcmAgZm9yIHRoaXNcbiAqIHJlcXVlc3RcIi5cbiAqXG4gKiBgYXNVc2VyKHJlcSlgIG5lZWRzIHRoZSBPQk8gdG9rZW4gdGhlIHBsYXRmb3JtIGZyb250IGRvb3IgZm9yd2FyZHMgb25cbiAqIHtAbGluayBBQ0NFU1NfVE9LRU5fSEVBREVSfS4gTWVhc3VyZWQgYWdhaW5zdCB0aGUgaW5zdGFsbGVkIEFwcEtpdCwgaXRzXG4gKiBiZWhhdmlvciB3aGVuIHRoYXQgaGVhZGVyIGlzIGFic2VudCBkZXBlbmRzIEVOVElSRUxZIG9uIGBOT0RFX0VOVmA6XG4gKlxuICogfCBgTk9ERV9FTlZgICAgIHwgbm8gYHgtZm9yd2FyZGVkLWFjY2Vzcy10b2tlbmAgICAgICAgICAgICAgICAgICAgICAgICB8XG4gKiB8IC0tLS0tLS0tLS0tLS0gfCAtLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tIHxcbiAqIHwgYGRldmVsb3BtZW50YCB8IGxvZ3MgYSB3YXJuaW5nLCBzaWxlbnRseSBydW5zIGFzIHRoZSBzZXJ2aWNlIHByaW5jaXBhbCB8XG4gKiB8IGFueXRoaW5nIGVsc2UgfCB0aHJvd3MgYEF1dGhlbnRpY2F0aW9uRXJyb3I6IE1pc3NpbmcgdXNlciB0b2tlbmAgICAgICB8XG4gKlxuICogVGhhdCBwcm9kdWN0aW9uIHRocm93IGlzIGNvcnJlY3QgZm9yIGFuIGFwcCBiZWhpbmQgdGhlIERhdGFicmlja3MgZnJvbnQgZG9vcixcbiAqIHdoZXJlIGEgbWlzc2luZyB0b2tlbiBtZWFucyBzb21ldGhpbmcgaXMgd3JvbmcuIEl0IGlzIGZhdGFsIGZvciBhbiBhcHAgd2hvc2VcbiAqIHRyYWZmaWMgbGVnaXRpbWF0ZWx5IGFycml2ZXMgV0lUSE9VVCBvbmU6XG4gKlxuICogICAtIGEgcHVibGljIHR1bm5lbCAoYEBkYngtdG9vbHMvY2xpLXR1bm5lbGApLCB3aGVyZSBjYWxsZXJzIGF1dGhlbnRpY2F0ZSBieVxuICogICAgIGVtYWlsIE9UUCBhbmQgbm8gT0JPIHRva2VuIGV4aXN0cyB0byBmb3J3YXJkIC0gdGhlIGdhdGUgY2FuIHByb3ZlIFdITyB0aGVcbiAqICAgICBjYWxsZXIgaXMsIGJ1dCBpdCBjYW5ub3QgbWludCBhIERhdGFicmlja3MgY3JlZGVudGlhbCBmb3IgdGhlbTtcbiAqICAgLSBhbnkgcmV2ZXJzZSBwcm94eSwgd2ViaG9vaywgb3IgYm90IGNoYW5uZWwgKGBQT1NUIC9hcGkvdGVhbXMvbWVzc2FnZXNgKVxuICogICAgIHRoYXQgYXV0aGVudGljYXRlcyBpdHMgb3duIHdheS5cbiAqXG4gKiBTdWNoIGFuIGFwcCBtdXN0IG5vdCBydW4gd2l0aCBgTk9ERV9FTlY9ZGV2ZWxvcG1lbnRgIGp1c3QgdG8gZ2V0IHRoZSBmYWxsYmFjazpcbiAqIHRoYXQgZmxhZyBhbHNvIHJlbGF4ZXMgc2VjdXJlIGNvb2tpZXMsIEFwcEtpdCdzIG93biBkZXYgYWZmb3JkYW5jZXMsIGFuZFxuICogYGFsbG93VW5hdXRoZW50aWNhdGVkYCBlc2NhcGUgaGF0Y2hlcy4gSGVuY2Uge0BsaW5rIElkZW50aXR5TW9kZX06XG4gKlxuICogICAtIGBcInVzZXJcImAgLSBhbHdheXMgT0JPLiBQZXItdXNlciBhdHRyaWJ1dGlvbiBhbmQgcGVyLXVzZXIgR2VuaWUgLyBVbml0eVxuICogICAgIENhdGFsb2cgcm93IGZpbHRlcnMuIENvcnJlY3Qgd2hlbiBldmVyeSBjYWxsZXIgaXMgYSB3b3Jrc3BhY2UgbWVtYmVyLlxuICogICAtIGBcInNlcnZpY2UtcHJpbmNpcGFsXCJgIC0gYWx3YXlzIHRoZSBhcHAncyBvd24gaWRlbnRpdHkuIE5lZWRzIG5vIE9CT1xuICogICAgIHNjb3BlcyBhbmQgd29ya3MgZm9yIGFueSBjYWxsZXIsIGF0IHRoZSBjb3N0IG9mIHBlci11c2VyIGRhdGEgc2NvcGluZy5cbiAqICAgLSBgXCJhdXRvXCJgIC0gT0JPIHdoZW4gdGhlIHJlcXVlc3QgYWN0dWFsbHkgY2FycmllcyBhIHVzYWJsZSBPQk8gdG9rZW4sXG4gKiAgICAgdGhlIHNlcnZpY2UgcHJpbmNpcGFsIG90aGVyd2lzZS4gT25lIGRlcGxveW1lbnQgdGhlbiBzZXJ2ZXMgQk9USCBkb29yc1xuICogICAgIGNvcnJlY3RseTogZnJvbnQtZG9vciByZXF1ZXN0cyBrZWVwIGZ1bGwgcGVyLXVzZXIgc2NvcGluZywgd2hpbGUgdHVubmVsIC9cbiAqICAgICB3ZWJob29rIHJlcXVlc3RzIGRlZ3JhZGUgdG8gdGhlIHNlcnZpY2UgcHJpbmNpcGFsIGluc3RlYWQgb2YgNTAwaW5nLlxuICpcbiAqIGBcImF1dG9cImAgZGVjaWRlcyBwZXIgUkVRVUVTVCwgbm90IHBlciBib290LCBiZWNhdXNlIGEgc2luZ2xlIGNvbnRhaW5lciBzZXJ2ZXNcbiAqIGJvdGggZG9vcnMgYXQgb25jZSAtIHRoZSB0dW5uZWwgZ2F0ZSBhbmQgdGhlIHBsYXRmb3JtIGZyb250IGRvb3Igc2hhcmUgYSBwb3J0XG4gKiAoc2VlIGBAZGJ4LXRvb2xzL2NsaS10dW5uZWxgKS4gQSBib290LXRpbWUgZmxhZyB3b3VsZCBoYXZlIHRvIGJlIHdyb25nIGZvciBvbmVcbiAqIG9mIHRoZW0uXG4gKlxuICogV2hhdCB0aGUgc2VydmljZSBwcmluY2lwYWwgZG9lcyBOT1QgY2hhbmdlIGlzIFdITyB0aGUgcmVxdWVzdCBiZWxvbmdzIHRvLiBUaGVcbiAqIGNhbGxlcidzIGlkZW50aXR5IHN0aWxsIGFycml2ZXMgb24ge0BsaW5rIFVTRVJfSURfSEVBREVSfSAvXG4gKiB7QGxpbmsgVVNFUl9FTUFJTF9IRUFERVJ9LCBzbyBtZW1vcnkgdGhyZWFkcywgY2FjaGUgbmFtZXNwYWNlcywgYW5kIHRyYWNlXG4gKiBhdHRyaWJ1dGlvbiBzdGF5IHBlci11c2VyLiBPbmx5IHRoZSBEYXRhYnJpY2tzIGNyZWRlbnRpYWwgaXMgc2hhcmVkLlxuICpcbiAqIEBtb2R1bGVcbiAqL1xuXG5pbXBvcnQgeyBDb25maWd1cmF0aW9uRXJyb3IgfSBmcm9tIFwiQGRhdGFicmlja3MvYXBwa2l0XCI7XG5pbXBvcnQgeyBlbnYsIHN0cmluZywgdG9rZW4sIHR5cGUgRW52S2V5IH0gZnJvbSBcIkBkYngtdG9vbHMvc2hhcmVkLWNvcmVcIjtcblxuLyoqXG4gKiBIZWFkZXIgdGhlIERhdGFicmlja3MgQXBwcyBmcm9udCBkb29yIGZvcndhcmRzIHRoZSBjYWxsZXIncyBPQk8gdG9rZW4gb24uXG4gKiBJdHMgcHJlc2VuY2UgaXMgd2hhdCBtYWtlcyBgYXNVc2VyKHJlcSlgIHZpYWJsZSwgc28gaXQgaXMgdGhlIHNpZ25hbFxuICoge0BsaW5rIHVzZVNlcnZpY2VQcmluY2lwYWx9IHJlYWRzIGluIGBcImF1dG9cImAgbW9kZS5cbiAqXG4gKiBSZS1leHBvcnRlZCBmcm9tIGBAZGJ4LXRvb2xzL3NoYXJlZC1jb3JlYCdzIGB0b2tlbmAgbW9kdWxlICh3aGljaCByZWFkcyB0aGVcbiAqIHNhbWUgaGVhZGVyIHRvIGRlY29kZSBPQXV0aCBzY29wZXMpIHJhdGhlciB0aGFuIHJlLXNwZWxsZWQsIHNvIHRoZSBuYW1lIGZvclxuICogdGhpcyB3aXJlIGNvbnRyYWN0IGV4aXN0cyBvbmNlLlxuICovXG5leHBvcnQgY29uc3QgQUNDRVNTX1RPS0VOX0hFQURFUiA9IHRva2VuLkFDQ0VTU19UT0tFTl9IRUFERVI7XG5cbi8qKiBIZWFkZXIgdGhlIERhdGFicmlja3MgQXBwcyBmcm9udCBkb29yIGZvcndhcmRzIHRoZSBjYWxsZXIncyB1c2VyIGlkIG9uLiAqL1xuZXhwb3J0IGNvbnN0IFVTRVJfSURfSEVBREVSID0gdG9rZW4uVVNFUl9JRF9IRUFERVI7XG5cbi8qKiBIZWFkZXIgdGhlIERhdGFicmlja3MgQXBwcyBmcm9udCBkb29yIGZvcndhcmRzIHRoZSBjYWxsZXIncyBlbWFpbCBvbi4gKi9cbmV4cG9ydCBjb25zdCBVU0VSX0VNQUlMX0hFQURFUiA9IHRva2VuLlVTRVJfRU1BSUxfSEVBREVSO1xuXG4vKiogSWRlbnRpdHkgYSByZXF1ZXN0J3MgRGF0YWJyaWNrcyBjYWxscyBydW4gYXMuIFNlZSB0aGUgbW9kdWxlIGRvY3MuICovXG5leHBvcnQgdHlwZSBJZGVudGl0eU1vZGUgPSBcInVzZXJcIiB8IFwic2VydmljZS1wcmluY2lwYWxcIiB8IFwiYXV0b1wiO1xuXG4vKiogRXZlcnkgYWNjZXB0ZWQge0BsaW5rIElkZW50aXR5TW9kZX0sIGluIHRoZSBvcmRlciBkb2NzIGFuZCBzY2hlbWFzIGxpc3QgdGhlbS4gKi9cbmV4cG9ydCBjb25zdCBJREVOVElUWV9NT0RFUzogcmVhZG9ubHkgSWRlbnRpdHlNb2RlW10gPSBbXCJ1c2VyXCIsIFwic2VydmljZS1wcmluY2lwYWxcIiwgXCJhdXRvXCJdO1xuXG4vKipcbiAqIERlZmF1bHQgbW9kZS4gYFwidXNlclwiYCBrZWVwcyBPQk8gdGhlIG9ubHkgaWRlbnRpdHkgdW5sZXNzIGFuIGFwcCBvcHRzIGluLCBzb1xuICogYWRvcHRpbmcgdGhpcyBvcHRpb24gY2FuIG5ldmVyIHNpbGVudGx5IHdpZGVuIGFuIGV4aXN0aW5nIGFwcCdzIGRhdGEgYWNjZXNzLlxuICovXG5leHBvcnQgY29uc3QgREVGQVVMVF9JREVOVElUWV9NT0RFOiBJZGVudGl0eU1vZGUgPSBcInVzZXJcIjtcblxuLyoqIFRoZSBzdWJzZXQgb2YgYGV4cHJlc3MuUmVxdWVzdGAgdGhpcyBtb2R1bGUgcmVhZHMgLSBvbmUgaGVhZGVyIGxvb2t1cC4gKi9cbmV4cG9ydCBpbnRlcmZhY2UgSGVhZGVyQmVhcmluZyB7XG4gIGhlYWRlcihuYW1lOiBzdHJpbmcpOiBzdHJpbmcgfCB1bmRlZmluZWQ7XG59XG5cbi8qKlxuICogUmVzb2x2ZSBhIGNvbmZpZ3VyZWQgbW9kZTogZXhwbGljaXQgY29uZmlnIHZhbHVlLCB0aGVuIHRoZSBmaXJzdCBub24tZW1wdHlcbiAqIHZhcmlhYmxlIGFtb25nIGBlbnZLZXlzYCwgdGhlbiB7QGxpbmsgREVGQVVMVF9JREVOVElUWV9NT0RFfS5cbiAqXG4gKiBBbiB1bnJlY29nbml6ZWQgdmFsdWUgdGhyb3dzIHJhdGhlciB0aGFuIGZhbGxpbmcgYmFjay4gRmFsbGluZyBiYWNrIHdvdWxkXG4gKiBzaWxlbnRseSBrZWVwIHNlcnZpbmcgT0JPIC0gYW5kIHRoZSBwcm9kdWN0aW9uIGBBdXRoZW50aWNhdGlvbkVycm9yYCBpdFxuICogcHJvZHVjZXMgLSB0byBleGFjdGx5IHRoZSBjYWxsZXJzIHRoZSBvcHRpb24gd2FzIHNldCB0byBhY2NvbW1vZGF0ZSwgYW5kIGFcbiAqIHR5cG8gKGBcIm9ib1wiYCwgYFwic3BcImApIGlzIHRoZSBsaWtlbGllc3Qgd2F5IHRvIGdldCBvbmUuXG4gKi9cbmV4cG9ydCBmdW5jdGlvbiByZXNvbHZlSWRlbnRpdHlNb2RlKFxuICBjb25maWd1cmVkOiBzdHJpbmcgfCB1bmRlZmluZWQsXG4gIGVudktleXM6IEVudktleSxcbiAgZmllbGQgPSBcImlkZW50aXR5XCIsXG4pOiBJZGVudGl0eU1vZGUge1xuICBjb25zdCByYXcgPSBlbnYuc3RyaW5nKGNvbmZpZ3VyZWQsIGVudktleXMpO1xuICBpZiAocmF3ID09PSBudWxsKSByZXR1cm4gREVGQVVMVF9JREVOVElUWV9NT0RFO1xuICBjb25zdCBtb2RlID0gcmF3LnRvTG93ZXJDYXNlKCkgYXMgSWRlbnRpdHlNb2RlO1xuICBpZiAoIUlERU5USVRZX01PREVTLmluY2x1ZGVzKG1vZGUpKSB7XG4gICAgY29uc3QgbmFtZXMgPSB0eXBlb2YgZW52S2V5cyA9PT0gXCJzdHJpbmdcIiA/IGVudktleXMgOiBlbnZLZXlzLmpvaW4oXCIgLyBcIik7XG4gICAgdGhyb3cgbmV3IENvbmZpZ3VyYXRpb25FcnJvcihcbiAgICAgIGAke2ZpZWxkfSBtdXN0IGJlIG9uZSBvZiAke0lERU5USVRZX01PREVTLmpvaW4oXCIgfCBcIil9IChlbnY6ICR7bmFtZXN9KWAsXG4gICAgICB7IGNvbnRleHQ6IHsgZmllbGQsIGVudlZhcjogbmFtZXMsIHJlY2VpdmVkOiByYXcgfSB9LFxuICAgICk7XG4gIH1cbiAgcmV0dXJuIG1vZGU7XG59XG5cbi8qKlxuICogVGhlIE9CTyB0b2tlbiBvbiBgcmVxYCwgb3IgYHVuZGVmaW5lZGAuIFJlYWQgdGhyb3VnaCB0aGUgc2FtZSB0cmltIGFzIGV2ZXJ5XG4gKiBvdGhlciBoZWFkZXIsIHNvIGEgaGVhZGVyIHByZXNlbnQtYnV0LWJsYW5rICh3aGljaCBzb21lIHByb3hpZXMgZW1pdCBmb3IgYW5cbiAqIHVuc2V0IHVwc3RyZWFtIHZhbHVlKSBjb3VudHMgYXMgYWJzZW50IHJhdGhlciB0aGFuIGFzIGEgdG9rZW4gdGhhdCBmYWlscyBhdFxuICogdGhlIGZpcnN0IERhdGFicmlja3MgY2FsbC5cbiAqL1xuZXhwb3J0IGZ1bmN0aW9uIHJlcXVlc3RBY2Nlc3NUb2tlbihyZXE6IEhlYWRlckJlYXJpbmcgfCB1bmRlZmluZWQpOiBzdHJpbmcgfCB1bmRlZmluZWQge1xuICByZXR1cm4gc3RyaW5nLnRyaW1Ub051bGwocmVxPy5oZWFkZXIoQUNDRVNTX1RPS0VOX0hFQURFUikpID8/IHVuZGVmaW5lZDtcbn1cblxuLyoqIFRoZSBmb3J3YXJkZWQgdXNlciBpZCBvbiBgcmVxYCwgb3IgYHVuZGVmaW5lZGAuICovXG5leHBvcnQgZnVuY3Rpb24gcmVxdWVzdFVzZXJJZChyZXE6IEhlYWRlckJlYXJpbmcgfCB1bmRlZmluZWQpOiBzdHJpbmcgfCB1bmRlZmluZWQge1xuICByZXR1cm4gc3RyaW5nLnRyaW1Ub051bGwocmVxPy5oZWFkZXIoVVNFUl9JRF9IRUFERVIpKSA/PyB1bmRlZmluZWQ7XG59XG5cbi8qKiBUaGUgZm9yd2FyZGVkIHVzZXIgZW1haWwgb24gYHJlcWAsIG9yIGB1bmRlZmluZWRgLiAqL1xuZXhwb3J0IGZ1bmN0aW9uIHJlcXVlc3RVc2VyRW1haWwocmVxOiBIZWFkZXJCZWFyaW5nIHwgdW5kZWZpbmVkKTogc3RyaW5nIHwgdW5kZWZpbmVkIHtcbiAgcmV0dXJuIHN0cmluZy50cmltVG9OdWxsKHJlcT8uaGVhZGVyKFVTRVJfRU1BSUxfSEVBREVSKSkgPz8gdW5kZWZpbmVkO1xufVxuXG4vKipcbiAqIFdoZXRoZXIgYHJlcWAgc2hvdWxkIHJ1biBpdHMgRGF0YWJyaWNrcyBjYWxscyBhcyB0aGUgYXBwIHNlcnZpY2UgcHJpbmNpcGFsXG4gKiByYXRoZXIgdGhhbiBPQk8uXG4gKlxuICogLSBgXCJzZXJ2aWNlLXByaW5jaXBhbFwiYCAtPiBhbHdheXMgYHRydWVgLlxuICogLSBgXCJ1c2VyXCJgIC0+IGFsd2F5cyBgZmFsc2VgLCBldmVuIHdpdGggbm8gdG9rZW4uIFRoZSBtb2RlIGlzIGFuIGV4cGxpY2l0XG4gKiAgIGFzc2VydGlvbiB0aGF0IGV2ZXJ5IGNhbGxlciBpcyBPQk8tY2FwYWJsZSwgc28gYSBtaXNzaW5nIHRva2VuIGlzIGEgcmVhbFxuICogICBlcnJvciBhbmQgbXVzdCBzdXJmYWNlIGFzIEFwcEtpdCdzIGBBdXRoZW50aWNhdGlvbkVycm9yYCByYXRoZXIgdGhhbiBiZWluZ1xuICogICBxdWlldGx5IGRvd25ncmFkZWQgdG8gc2hhcmVkIGRhdGEgYWNjZXNzLlxuICogLSBgXCJhdXRvXCJgIC0+IGB0cnVlYCBvbmx5IHdoZW4gdGhlIHJlcXVlc3QgY2FycmllcyBubyB1c2FibGUgT0JPIHRva2VuLlxuICpcbiAqIEEgcmVxdWVzdCBBcHBLaXQgd2lsbCBub3QgYWNjZXB0IGZvciBPQk8gYW55d2F5IChubyB0b2tlbikgY2FuIG5ldmVyIGJlXG4gKiBzZXJ2ZWQgYnkgZW50ZXJpbmcgYGFzVXNlcmAsIHNvIGluIGBcImF1dG9cImAgbW9kZSB0aGUgdG9rZW4gY2hlY2sgaXMgdGhlIHdob2xlXG4gKiBkZWNpc2lvbjogaXQgaXMgdGhlIHNhbWUgY29uZGl0aW9uIEFwcEtpdCBpdHNlbGYgYnJhbmNoZXMgb24sIGp1c3QgcmVzb2x2ZWRcbiAqIGJlZm9yZSBpdCBjYW4gdGhyb3cuXG4gKi9cbmV4cG9ydCBmdW5jdGlvbiB1c2VTZXJ2aWNlUHJpbmNpcGFsKG1vZGU6IElkZW50aXR5TW9kZSwgcmVxPzogSGVhZGVyQmVhcmluZyk6IGJvb2xlYW4ge1xuICBpZiAobW9kZSA9PT0gXCJzZXJ2aWNlLXByaW5jaXBhbFwiKSByZXR1cm4gdHJ1ZTtcbiAgaWYgKG1vZGUgPT09IFwidXNlclwiKSByZXR1cm4gZmFsc2U7XG4gIHJldHVybiByZXF1ZXN0QWNjZXNzVG9rZW4ocmVxKSA9PT0gdW5kZWZpbmVkO1xufVxuIl19

package/lib/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["../src/appkit.ts","../src/config.ts","../src/create-app.ts","../src/databricks.ts","../src/lakebase-resolver.ts","../src/pgaddress.ts","../src/plugin.ts","../src/provision.ts","../index.ts"],"version":"5.9.3"}
+{"root":["../src/appkit.ts","../src/config.ts","../src/create-app.ts","../src/databricks.ts","../src/identity.ts","../src/lakebase-resolver.ts","../src/pgaddress.ts","../src/plugin.ts","../src/provision.ts","../index.ts"],"version":"5.9.3"}

package/package.json

@@ -28,8 +28,8 @@
   },
   "dependencies": {
     "@databricks/sdk-experimental": "^0.17.0",
-    "@dbx-tools/core": "0.6.48",
-    "@dbx-tools/shared-core": "0.6.48",
+    "@dbx-tools/core": "0.6.49",
+    "@dbx-tools/shared-core": "0.6.49",
     "yaml": "^2.9.0",
     "zod": "4.3.6"
   },
@@ -47,7 +47,7 @@
       "./package.json": "./package.json"
     }
   },
-  "version": "0.6.48",
+  "version": "0.6.49",
   "types": "./lib/index.d.ts",
   "type": "module",
   "exports": {

package/src/identity.ts

@@ -0,0 +1,159 @@
+/**
+ * Which Databricks identity a request's workspace calls run as.
+ *
+ * AppKit gives a plugin two identities: the ambient SERVICE context (the app's
+ * own service principal) and a per-request USER context entered with
+ * `asUser(req)`, which authenticates as the caller on-behalf-of (OBO). The
+ * choice is one call, so the whole decision is "do we enter `asUser` for this
+ * request".
+ *
+ * `asUser(req)` needs the OBO token the platform front door forwards on
+ * {@link ACCESS_TOKEN_HEADER}. Measured against the installed AppKit, its
+ * behavior when that header is absent depends ENTIRELY on `NODE_ENV`:
+ *
+ * | `NODE_ENV`    | no `x-forwarded-access-token`                        |
+ * | ------------- | ---------------------------------------------------- |
+ * | `development` | logs a warning, silently runs as the service principal |
+ * | anything else | throws `AuthenticationError: Missing user token`      |
+ *
+ * That production throw is correct for an app behind the Databricks front door,
+ * where a missing token means something is wrong. It is fatal for an app whose
+ * traffic legitimately arrives WITHOUT one:
+ *
+ *   - a public tunnel (`@dbx-tools/cli-tunnel`), where callers authenticate by
+ *     email OTP and no OBO token exists to forward - the gate can prove WHO the
+ *     caller is, but it cannot mint a Databricks credential for them;
+ *   - any reverse proxy, webhook, or bot channel (`POST /api/teams/messages`)
+ *     that authenticates its own way.
+ *
+ * Such an app must not run with `NODE_ENV=development` just to get the fallback:
+ * that flag also relaxes secure cookies, AppKit's own dev affordances, and
+ * `allowUnauthenticated` escape hatches. Hence {@link IdentityMode}:
+ *
+ *   - `"user"` - always OBO. Per-user attribution and per-user Genie / Unity
+ *     Catalog row filters. Correct when every caller is a workspace member.
+ *   - `"service-principal"` - always the app's own identity. Needs no OBO
+ *     scopes and works for any caller, at the cost of per-user data scoping.
+ *   - `"auto"` - OBO when the request actually carries a usable OBO token,
+ *     the service principal otherwise. One deployment then serves BOTH doors
+ *     correctly: front-door requests keep full per-user scoping, while tunnel /
+ *     webhook requests degrade to the service principal instead of 500ing.
+ *
+ * `"auto"` decides per REQUEST, not per boot, because a single container serves
+ * both doors at once - the tunnel gate and the platform front door share a port
+ * (see `@dbx-tools/cli-tunnel`). A boot-time flag would have to be wrong for one
+ * of them.
+ *
+ * What the service principal does NOT change is WHO the request belongs to. The
+ * caller's identity still arrives on {@link USER_ID_HEADER} /
+ * {@link USER_EMAIL_HEADER}, so memory threads, cache namespaces, and trace
+ * attribution stay per-user. Only the Databricks credential is shared.
+ *
+ * @module
+ */
+
+import { ConfigurationError } from "@databricks/appkit";
+import { env, string, token, type EnvKey } from "@dbx-tools/shared-core";
+
+/**
+ * Header the Databricks Apps front door forwards the caller's OBO token on.
+ * Its presence is what makes `asUser(req)` viable, so it is the signal
+ * {@link useServicePrincipal} reads in `"auto"` mode.
+ *
+ * Re-exported from `@dbx-tools/shared-core`'s `token` module (which reads the
+ * same header to decode OAuth scopes) rather than re-spelled, so the name for
+ * this wire contract exists once.
+ */
+export const ACCESS_TOKEN_HEADER = token.ACCESS_TOKEN_HEADER;
+
+/** Header the Databricks Apps front door forwards the caller's user id on. */
+export const USER_ID_HEADER = token.USER_ID_HEADER;
+
+/** Header the Databricks Apps front door forwards the caller's email on. */
+export const USER_EMAIL_HEADER = token.USER_EMAIL_HEADER;
+
+/** Identity a request's Databricks calls run as. See the module docs. */
+export type IdentityMode = "user" | "service-principal" | "auto";
+
+/** Every accepted {@link IdentityMode}, in the order docs and schemas list them. */
+export const IDENTITY_MODES: readonly IdentityMode[] = ["user", "service-principal", "auto"];
+
+/**
+ * Default mode. `"user"` keeps OBO the only identity unless an app opts in, so
+ * adopting this option can never silently widen an existing app's data access.
+ */
+export const DEFAULT_IDENTITY_MODE: IdentityMode = "user";
+
+/** The subset of `express.Request` this module reads - one header lookup. */
+export interface HeaderBearing {
+  header(name: string): string | undefined;
+}
+
+/**
+ * Resolve a configured mode: explicit config value, then the first non-empty
+ * variable among `envKeys`, then {@link DEFAULT_IDENTITY_MODE}.
+ *
+ * An unrecognized value throws rather than falling back. Falling back would
+ * silently keep serving OBO - and the production `AuthenticationError` it
+ * produces - to exactly the callers the option was set to accommodate, and a
+ * typo (`"obo"`, `"sp"`) is the likeliest way to get one.
+ */
+export function resolveIdentityMode(
+  configured: string | undefined,
+  envKeys: EnvKey,
+  field = "identity",
+): IdentityMode {
+  const raw = env.string(configured, envKeys);
+  if (raw === null) return DEFAULT_IDENTITY_MODE;
+  const mode = raw.toLowerCase() as IdentityMode;
+  if (!IDENTITY_MODES.includes(mode)) {
+    const names = typeof envKeys === "string" ? envKeys : envKeys.join(" / ");
+    throw new ConfigurationError(
+      `${field} must be one of ${IDENTITY_MODES.join(" | ")} (env: ${names})`,
+      { context: { field, envVar: names, received: raw } },
+    );
+  }
+  return mode;
+}
+
+/**
+ * The OBO token on `req`, or `undefined`. Read through the same trim as every
+ * other header, so a header present-but-blank (which some proxies emit for an
+ * unset upstream value) counts as absent rather than as a token that fails at
+ * the first Databricks call.
+ */
+export function requestAccessToken(req: HeaderBearing | undefined): string | undefined {
+  return string.trimToNull(req?.header(ACCESS_TOKEN_HEADER)) ?? undefined;
+}
+
+/** The forwarded user id on `req`, or `undefined`. */
+export function requestUserId(req: HeaderBearing | undefined): string | undefined {
+  return string.trimToNull(req?.header(USER_ID_HEADER)) ?? undefined;
+}
+
+/** The forwarded user email on `req`, or `undefined`. */
+export function requestUserEmail(req: HeaderBearing | undefined): string | undefined {
+  return string.trimToNull(req?.header(USER_EMAIL_HEADER)) ?? undefined;
+}
+
+/**
+ * Whether `req` should run its Databricks calls as the app service principal
+ * rather than OBO.
+ *
+ * - `"service-principal"` -> always `true`.
+ * - `"user"` -> always `false`, even with no token. The mode is an explicit
+ *   assertion that every caller is OBO-capable, so a missing token is a real
+ *   error and must surface as AppKit's `AuthenticationError` rather than being
+ *   quietly downgraded to shared data access.
+ * - `"auto"` -> `true` only when the request carries no usable OBO token.
+ *
+ * A request AppKit will not accept for OBO anyway (no token) can never be
+ * served by entering `asUser`, so in `"auto"` mode the token check is the whole
+ * decision: it is the same condition AppKit itself branches on, just resolved
+ * before it can throw.
+ */
+export function useServicePrincipal(mode: IdentityMode, req?: HeaderBearing): boolean {
+  if (mode === "service-principal") return true;
+  if (mode === "user") return false;
+  return requestAccessToken(req) === undefined;
+}