databricks
diff --git a/‎lib/sea/SeaAuth.ts‎
Lines changed: 62 additions & 31 deletions b/‎lib/sea/SeaAuth.ts‎
Lines changed: 62 additions & 31 deletions
diff --git a/‎lib/sea/SeaBackend.ts‎
Lines changed: 7 additions & 1 deletion b/‎lib/sea/SeaBackend.ts‎
Lines changed: 7 additions & 1 deletion
diff --git a/‎lib/sea/SeaErrorMapping.ts‎
Lines changed: 63 additions & 0 deletions b/‎lib/sea/SeaErrorMapping.ts‎
Lines changed: 63 additions & 0 deletions
diff --git a/‎tests/integration/sea/auth-m2m-e2e.test.ts‎
Lines changed: 40 additions & 1 deletion b/‎tests/integration/sea/auth-m2m-e2e.test.ts‎
Lines changed: 40 additions & 1 deletion
@@ -77,6 +77,19 @@ function prependSlash(str: string): string {
   return str;
 }
 
+/**
+ * Reject inputs that pass `typeof === 'string' && length > 0` but are
+ * structurally useless as credentials: whitespace-only strings, and the
+ * literal strings `'undefined'` / `'null'` that buggy shell exports
+ * (e.g. `export FOO="$UNSET_VAR"`) produce. Surfacing these here means
+ * an OAuth flow's `invalid_client` from the workspace is always a real
+ * credential mismatch, never a malformed-input passthrough.
+ */
+function isBlankOrReserved(s: string): boolean {
+  const trimmed = s.trim();
+  return trimmed.length === 0 || trimmed === 'undefined' || trimmed === 'null';
+}
+
 /**
  * Validate the user-supplied `ConnectionOptions` and build the
  * napi-binding's connection-options shape.
@@ -87,9 +100,7 @@ function prependSlash(str: string): string {
  *     `DBSQLClient.createAuthProvider`).
  *   - OAuth M2M: `authType: 'databricks-oauth'` + `oauthClientId` +
  *     `oauthClientSecret`. Kernel handles OIDC discovery, client_credentials
- *     exchange, and re-auth on expiry internally (no caching needed — M2M
- *     never has a refresh token; see `auth/oauth/m2m.rs` and the thrift
- *     parity note at `OAuthManager.ts:178-181`).
+ *     exchange, and re-auth on expiry internally.
  *   - OAuth U2M: `authType: 'databricks-oauth'` + NO `oauthClientSecret`.
  *     Kernel runs the PKCE auth-code dance (opens a browser, listens on
  *     localhost:8030, exchanges the code, persists to
@@ -99,20 +110,24 @@ function prependSlash(str: string): string {
  *
  * Out of scope on the OAuth paths (rejected with a clear error):
  *   - `azureTenantId` / `useDatabricksOAuthInAzure` → Microsoft Entra
- *     direct flow with `<tenantId>/.default` scope rewrite. The kernel
- *     uses workspace-OIDC discovery (which works against Azure workspaces
- *     too — they serve `/oidc/.well-known/...`); Entra-direct is a
- *     follow-on M1 Phase 2 task.
- *   - `persistence` on either flavor — for M2M the kernel doesn't cache
- *     (re-issuing is cheap; M2M has no refresh token). For U2M, custom
- *     persistence requires the kernel to expose `AuthConfig::External`
- *     (M1 Phase 2 task). The kernel-internal disk cache works for the
- *     standard flow today.
+ *     direct flow. The kernel uses workspace-OIDC discovery (which works
+ *     against Azure workspaces too — they serve `/oidc/.well-known/...`)
+ *     and does not implement the Entra-direct scope-rewrite path.
+ *   - `persistence` on M2M → M2M tokens are not cached (re-issuing is
+ *     cheap; no refresh token).
+ *   - `persistence` on U2M → custom token store is a parity gap;
+ *     requires kernel-side `AuthConfig::External` plumbing. The kernel's
+ *     auto-disk-cache works for the standard flow today.
+ *
+ * Ambiguity:
+ *   - PAT path: rejects when OAuth fields (`oauthClientId` /
+ *     `oauthClientSecret`) are simultaneously set.
+ *   - OAuth path: rejects when `token` is set alongside OAuth fields.
  *
  * Throws:
- *   - `AuthenticationError` for missing required credentials.
+ *   - `AuthenticationError` for missing/blank required credentials.
  *   - `HiveDriverError` for unsupported auth modes / Azure-direct /
- *     custom persistence.
+ *     custom persistence / ambiguous combinations.
  */
 export function buildSeaConnectionOptions(options: ConnectionOptions): SeaNativeConnectionOptions {
   const { authType } = options as { authType?: string };
@@ -122,30 +137,44 @@ export function buildSeaConnectionOptions(options: ConnectionOptions): SeaNative
     httpPath: prependSlash(options.path),
   };
 
+  const oauth = options as {
+    oauthClientId?: string;
+    oauthClientSecret?: string;
+    azureTenantId?: string;
+    useDatabricksOAuthInAzure?: boolean;
+    persistence?: unknown;
+  };
+
   if (authType === undefined || authType === 'access-token') {
     const { token } = options as { token?: string };
-    if (typeof token !== 'string' || token.length === 0) {
+    if (typeof token !== 'string' || isBlankOrReserved(token)) {
       throw new AuthenticationError(
         'SEA backend: a non-empty PAT must be supplied via `token` when using `authType: \'access-token\'`.',
       );
     }
+    if (oauth.oauthClientId !== undefined || oauth.oauthClientSecret !== undefined) {
+      throw new HiveDriverError(
+        'SEA backend: cannot supply both `token` and `oauthClientId`/`oauthClientSecret` ' +
+          "on the same connection. Pick one: 'access-token' (PAT) uses `token`; " +
+          "'databricks-oauth' uses the OAuth fields.",
+      );
+    }
     return { ...base, authMode: 'Pat', token };
   }
 
   if (authType === 'databricks-oauth') {
-    const oauth = options as {
-      oauthClientId?: string;
-      oauthClientSecret?: string;
-      azureTenantId?: string;
-      useDatabricksOAuthInAzure?: boolean;
-      persistence?: unknown;
-    };
+    if ((options as { token?: string }).token !== undefined) {
+      throw new HiveDriverError(
+        "SEA backend: cannot supply `token` alongside `authType: 'databricks-oauth'`. " +
+          "Use `authType: 'access-token'` for PAT, or omit `token` to use OAuth.",
+      );
+    }
 
     if (oauth.azureTenantId !== undefined || oauth.useDatabricksOAuthInAzure === true) {
       throw new HiveDriverError(
         'SEA backend: Azure-direct OAuth (azureTenantId / useDatabricksOAuthInAzure) ' +
-          'is a later M1 task; the kernel uses workspace-OIDC discovery today, ' +
-          'which works against Azure workspaces with no extra options.',
+          'is not supported. The workspace-OIDC discovery path handles Azure workspaces ' +
+          'today without these options.',
       );
     }
 
@@ -156,7 +185,7 @@ export function buildSeaConnectionOptions(options: ConnectionOptions): SeaNative
       if (oauth.persistence !== undefined) {
         throw new HiveDriverError(
           'SEA backend: `persistence` (custom OAuth token store) is not yet wired through ' +
-            'to the kernel — requires `AuthConfig::External` plumbing planned for M1 Phase 2. ' +
+            'to the kernel — requires `AuthConfig::External` plumbing. ' +
             'Today the kernel auto-persists U2M tokens to ' +
             '`~/.config/databricks-sql-kernel/oauth/` which works for the standard flow; ' +
             "the JS-supplied hook (matching thrift's `OAuthPersistence` interface) lands " +
@@ -171,12 +200,14 @@ export function buildSeaConnectionOptions(options: ConnectionOptions): SeaNative
     }
 
     // M2M.
-    if (typeof oauth.oauthClientId !== 'string' || oauth.oauthClientId.length === 0) {
-      throw new AuthenticationError('SEA backend: `oauthClientId` is required for OAuth M2M.');
+    if (typeof oauth.oauthClientId !== 'string' || isBlankOrReserved(oauth.oauthClientId)) {
+      throw new AuthenticationError(
+        'SEA backend: `oauthClientId` is required (non-empty, non-whitespace) for OAuth M2M.',
+      );
     }
-    if (typeof oauth.oauthClientSecret !== 'string' || oauth.oauthClientSecret.length === 0) {
+    if (typeof oauth.oauthClientSecret !== 'string' || isBlankOrReserved(oauth.oauthClientSecret)) {
       throw new AuthenticationError(
-        'SEA backend: `oauthClientSecret` must be a non-empty string for OAuth M2M.',
+        'SEA backend: `oauthClientSecret` must be a non-empty non-whitespace string for OAuth M2M.',
       );
     }
     if (oauth.persistence !== undefined) {
@@ -195,7 +226,7 @@ export function buildSeaConnectionOptions(options: ConnectionOptions): SeaNative
 
   throw new HiveDriverError(
     `SEA backend: unsupported auth mode '${authType}'. ` +
-      `Supported modes today: 'access-token' (PAT), 'databricks-oauth' (M2M + U2M). ` +
-      `Other modes (token-provider, external-token, static-token, custom) are M1+ follow-ups.`,
+      "Supported modes on the SEA backend today: 'access-token' (PAT) and 'databricks-oauth' " +
+      '(M2M with oauthClientId+oauthClientSecret, or U2M with neither).',
   );
 }
@@ -33,6 +33,7 @@ import InfoValue from '../dto/InfoValue';
 import HiveDriverError from '../errors/HiveDriverError';
 import { getSeaNative, SeaNativeBinding } from './SeaNativeLoader';
 import { buildSeaConnectionOptions, SeaNativeConnectionOptions } from './SeaAuth';
+import { decodeNapiKernelError } from './SeaErrorMapping';
 
 const NOT_IMPLEMENTED_SESSION =
   'SEA session backend: method not implemented in sea-auth (M0); lands in sea-execution/sea-operation.';
@@ -158,7 +159,12 @@ export default class SeaBackend implements IBackend {
     if (!this.nativeOptions) {
       throw new HiveDriverError('SeaBackend: connect() must be called before openSession().');
     }
-    const connection = (await this.native.openSession(this.nativeOptions)) as NativeConnection;
+    let connection: NativeConnection;
+    try {
+      connection = (await this.native.openSession(this.nativeOptions)) as NativeConnection;
+    } catch (err) {
+      throw decodeNapiKernelError(err);
+    }
     return new SeaSessionBackend(connection);
   }
 
 
@@ -3,6 +3,15 @@ import AuthenticationError from '../errors/AuthenticationError';
 import OperationStateError, { OperationStateErrorCode } from '../errors/OperationStateError';
 import ParameterError from '../errors/ParameterError';
 
+/**
+ * Sentinel prefix the napi binding's `napi_err_from_kernel` puts on
+ * `Error.message` when the underlying failure was a structured kernel
+ * `Error` rather than a plain napi `InvalidArg` from binding-side
+ * validation. Defined here (and in `native/sea/src/error.rs:44`) — the
+ * two MUST stay in lockstep.
+ */
+const ERROR_SENTINEL = '__databricks_error__:';
+
 /**
  * Shape of the kernel error surfaced by the napi-binding's `napi_err_from_kernel`.
  *
@@ -139,3 +148,57 @@ export function mapKernelErrorToJsError(kErr: KernelErrorShape): ErrorWithSqlSta
 
   return attachSqlState(error, sqlstate);
 }
+
+/**
+ * Decode a napi-binding error into the typed JS error class.
+ *
+ * Two paths:
+ *  - Structured kernel error: `Error.message` starts with
+ *    {@link ERROR_SENTINEL} followed by a JSON envelope. We strip the
+ *    sentinel, parse the JSON, and route through
+ *    {@link mapKernelErrorToJsError}.
+ *  - Binding-side error (e.g. `napi::Error::new(InvalidArg, "openSession:
+ *    \`token\` is required for the requested auth mode")` produced by
+ *    the binding's own validation): returned unchanged. These don't
+ *    carry kernel `code` info, so we surface them as-is.
+ *
+ * Non-`Error` values (e.g. a `Promise.reject('string')`) pass through
+ * wrapped in `HiveDriverError` so callers always see an `Error`
+ * subclass.
+ */
+export function decodeNapiKernelError(err: unknown): Error {
+  if (!(err instanceof Error)) {
+    return new HiveDriverError(typeof err === 'string' ? err : 'SEA backend: unknown error');
+  }
+
+  const { message } = err;
+  if (typeof message !== 'string' || !message.startsWith(ERROR_SENTINEL)) {
+    return err;
+  }
+
+  const jsonStr = message.slice(ERROR_SENTINEL.length);
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(jsonStr);
+  } catch {
+    // Corrupted envelope — surface the raw message rather than
+    // silently dropping the original error.
+    return err;
+  }
+
+  if (
+    typeof parsed !== 'object' ||
+    parsed === null ||
+    typeof (parsed as { code?: unknown }).code !== 'string' ||
+    typeof (parsed as { message?: unknown }).message !== 'string'
+  ) {
+    return err;
+  }
+
+  const kErr = parsed as { code: string; message: string; sqlState?: string };
+  return mapKernelErrorToJsError({
+    code: kErr.code,
+    message: kErr.message,
+    sqlstate: kErr.sqlState,
+  });
+}
@@ -14,6 +14,7 @@
 
 import { expect } from 'chai';
 import { DBSQLClient } from '../../../lib';
+import AuthenticationError from '../../../lib/errors/AuthenticationError';
 
 /**
  * sea-auth M1 OAuth M2M end-to-end:
@@ -49,7 +50,17 @@ describe('sea-auth e2e — OAuth M2M through DBSQLClient ↔ SeaBackend ↔ napi
   this.timeout(120_000);
 
   before(function gate() {
-    if (!host || !path || !oauthClientId || !oauthClientSecret) {
+    // Reject not just absent env vars but also literal `'undefined'` /
+    // `'null'` / whitespace-only values from buggy shell exports — these
+    // would otherwise reach the workspace as bogus creds and yield an
+    // `invalid_client` indistinguishable from a real SP-not-registered
+    // issue.
+    const looksReal = (s: string | undefined): s is string => {
+      if (typeof s !== 'string') return false;
+      const t = s.trim();
+      return t.length > 0 && t !== 'undefined' && t !== 'null';
+    };
+    if (!looksReal(host) || !looksReal(path) || !looksReal(oauthClientId) || !looksReal(oauthClientSecret)) {
       // eslint-disable-next-line no-invalid-this
       this.skip();
     }
@@ -77,4 +88,32 @@ describe('sea-auth e2e — OAuth M2M through DBSQLClient ↔ SeaBackend ↔ napi
 
     await client.close();
   });
+
+  // Negative path — proves the kernel-side OAuth error path is intact
+  // and surfaces as the typed `AuthenticationError` (DA-F1 + DA-F6).
+  // Distinguishes "creds wrong" (this test passes with bogus secret)
+  // from "all code broken" (this test fails with a non-AuthenticationError).
+  it('rejects with AuthenticationError when oauthClientSecret is deliberately wrong', async () => {
+    const client = new DBSQLClient();
+
+    await client.connect({
+      host: host as string,
+      path: path as string,
+      authType: 'databricks-oauth',
+      oauthClientId: oauthClientId as string,
+      oauthClientSecret: 'definitely-not-the-real-secret-deadbeef',
+      useSEA: true,
+    });
+
+    let caught: unknown;
+    try {
+      await client.openSession();
+    } catch (e) {
+      caught = e;
+    }
+    expect(caught).to.be.instanceOf(AuthenticationError);
+    expect((caught as Error).message).to.match(/invalid_client/i);
+
+    await client.close();
+  });
 });