@blaxel/core 0.2.87-preview.169 → 0.2.87-preview.171

package/dist/esm-browser/authentication/credentials.js

@@ -11,3 +11,12 @@ export class Credentials {
         return "";
     }
 }
+/**
+ * Marker returned by `authentication()` when no usable Blaxel credentials were
+ * resolved (no env vars, no matching config workspace). Construction is
+ * side-effect free so importing `@blaxel/core` never fails; the actionable
+ * error is raised when an authenticated request is actually attempted
+ * (see `Settings.assertCredentials`).
+ */
+export class MissingCredentials extends Credentials {
+}

package/dist/esm-browser/authentication/index.js

@@ -3,7 +3,7 @@ import { env } from "../common/env.js";
 import { fs, os, path } from "../common/node.js";
 import { ApiKey } from "./apikey.js";
 import { ClientCredentials } from "./clientcredentials.js";
-import { Credentials } from "./credentials.js";
+import { Credentials, MissingCredentials } from "./credentials.js";
 import { DeviceMode } from "./deviceMode.js";
 function getCredentials() {
     if (env.BL_API_KEY) {
@@ -45,7 +45,9 @@ function getCredentials() {
 export function authentication() {
     const credentials = getCredentials();
     if (!credentials) {
-        return new Credentials();
+        // Never silently fall back to empty headers: a marker that triggers a
+        // clear CredentialsError when an authenticated request is attempted.
+        return new MissingCredentials();
     }
     if (credentials.apiKey) {
         return new ApiKey(credentials);

package/dist/esm-browser/common/credentials.test.js

@@ -0,0 +1,69 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { ApiKey } from '../authentication/apikey.js';
+import { MissingCredentials } from '../authentication/credentials.js';
+import { authentication } from '../authentication/index.js';
+import { CredentialsError } from './errors.js';
+import { settings } from './settings.js';
+/**
+ * ENG-2698: missing / partial BL_WORKSPACE / BL_API_KEY must fail fast with a
+ * clear, actionable error instead of silently sending empty headers and
+ * surfacing the server's misleading "workspace is required".
+ *
+ * `env` reads through to `process.env`, so env state is controlled there.
+ */
+describe('credential validation', () => {
+    const AUTH_ENV = ['BL_API_KEY', 'BL_WORKSPACE', 'BL_CLIENT_CREDENTIALS'];
+    let savedEnv;
+    let savedCredentials;
+    let savedConfig;
+    beforeEach(() => {
+        savedEnv = {};
+        for (const key of AUTH_ENV) {
+            savedEnv[key] = process.env[key];
+            delete process.env[key];
+        }
+        savedCredentials = settings.credentials;
+        savedConfig = settings.config;
+        settings.config = { proxy: '', apikey: '', workspace: '' };
+    });
+    afterEach(() => {
+        for (const key of AUTH_ENV) {
+            if (savedEnv[key] === undefined)
+                delete process.env[key];
+            else
+                process.env[key] = savedEnv[key];
+        }
+        settings.credentials = savedCredentials;
+        settings.config = savedConfig;
+    });
+    it('API key without workspace throws a clear BL_WORKSPACE error from headers', () => {
+        settings.credentials = new ApiKey({ apiKey: 'test-key' });
+        expect(() => settings.headers).toThrow(CredentialsError);
+        expect(() => settings.headers).toThrow(/BL_WORKSPACE/);
+    });
+    it('API key without workspace rejects from authenticate()', async () => {
+        settings.credentials = new ApiKey({ apiKey: 'test-key' });
+        await expect(settings.authenticate()).rejects.toThrow(/BL_WORKSPACE/);
+    });
+    it('workspace set but no API key names the missing API key', () => {
+        process.env.BL_WORKSPACE = 'my-workspace';
+        settings.credentials = new MissingCredentials();
+        expect(() => settings.headers).toThrow(/API key is missing/);
+    });
+    it('no credentials at all names both env vars', () => {
+        settings.credentials = new MissingCredentials();
+        expect(() => settings.headers).toThrow(CredentialsError);
+        expect(() => settings.headers).toThrow(/BL_API_KEY and BL_WORKSPACE/);
+    });
+    it('api key + workspace builds clean headers with no empty values', () => {
+        settings.credentials = new ApiKey({ apiKey: 'test-key', workspace: 'my-workspace' });
+        const headers = settings.headers;
+        expect(headers['x-blaxel-workspace']).toBe('my-workspace');
+        expect(headers['x-blaxel-authorization']).toBe('Bearer test-key');
+        expect(Object.values(headers)).not.toContain('');
+    });
+    it('authentication() returns a real ApiKey when BL_API_KEY is set', () => {
+        process.env.BL_API_KEY = 'test-key';
+        expect(authentication()).toBeInstanceOf(ApiKey);
+    });
+});

package/dist/esm-browser/common/errors.js

@@ -1,3 +1,16 @@
+/**
+ * Thrown when Blaxel credentials are missing or incomplete.
+ *
+ * Surfaced eagerly with an actionable message (which env var / login step is
+ * missing) instead of silently sending empty workspace/authorization headers
+ * and letting the user hit a misleading server-side "workspace is required".
+ */
+export class CredentialsError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CredentialsError";
+    }
+}
 export function handleDynamicImportError(err) {
     if (err instanceof Error) {
         // We check if it's module import error and retrieve package name from the error message with a regex

package/dist/esm-browser/common/settings.js

@@ -1,12 +1,29 @@
 import yaml from 'yaml';
 import { ApiKey } from "../authentication/apikey.js";
 import { ClientCredentials } from "../authentication/clientcredentials.js";
+import { MissingCredentials } from "../authentication/credentials.js";
 import { authentication } from "../authentication/index.js";
 import { env } from "../common/env.js";
+import { CredentialsError } from "../common/errors.js";
 import { fs, os, path } from "../common/node.js";
+/**
+ * Build an actionable "credentials missing" message naming exactly which piece
+ * is absent, based on the env vars currently set.
+ */
+function missingCredentialsMessage() {
+    const hasWorkspace = !!env.BL_WORKSPACE;
+    const hasApiKey = !!env.BL_API_KEY;
+    if (hasWorkspace && !hasApiKey) {
+        return "Blaxel API key is missing. Set the BL_API_KEY environment variable, or run `bl login`, to authenticate (BL_WORKSPACE is already set).";
+    }
+    if (hasApiKey && !hasWorkspace) {
+        return "Blaxel workspace is missing. Set the BL_WORKSPACE environment variable, or run `bl login`, to authenticate (BL_API_KEY is already set).";
+    }
+    return "No Blaxel credentials found. Set the BL_API_KEY and BL_WORKSPACE environment variables, or run `bl login`.";
+}
 // Build info - these placeholders are replaced at build time by build:replace-imports
-const BUILD_VERSION = "0.2.87-preview.169";
-const BUILD_COMMIT = "5357b12d98548db2b306537be7d96d2888ac8cb1";
+const BUILD_VERSION = "0.2.87-preview.171";
+const BUILD_COMMIT = "06530fbea3b8ff89d51d0b834de6725ad5ad80ee";
 const BUILD_SENTRY_DSN = "https://fd5e60e1c9820e1eef5ccebb84a07127@o4508714045276160.ingest.us.sentry.io/4510465864564736";
 const BLAXEL_API_VERSION = "2026-04-16";
 // Cache for config.yaml tracking value
@@ -167,6 +184,7 @@ class Settings {
         return env.BL_API_VERSION || BLAXEL_API_VERSION;
     }
     get headers() {
+        this.assertCredentials();
         const osArch = getOsArch();
         return {
             "x-blaxel-authorization": this.authorization,
@@ -252,7 +270,27 @@ class Settings {
         }
         return 0;
     }
+    /**
+     * Fail fast with a clear, actionable error when credentials are missing or
+     * incomplete, instead of sending empty workspace/authorization headers and
+     * surfacing a misleading server-side "workspace is required". Skipped for
+     * `forceUrl` sandbox sessions, which carry their own headers and never read
+     * `settings.headers`. Leaves `workspace` itself non-throwing so telemetry
+     * tagging stays safe.
+     */
+    assertCredentials() {
+        const hasConfigCredentials = !!(this.config.apikey ||
+            this.config.apiKey ||
+            this.config.clientCredentials);
+        if (!hasConfigCredentials && this.credentials instanceof MissingCredentials) {
+            throw new CredentialsError(missingCredentialsMessage());
+        }
+        if (!this.workspace) {
+            throw new CredentialsError("Blaxel workspace is missing. Set the BL_WORKSPACE environment variable, or run `bl login`, to authenticate your requests.");
+        }
+    }
     async authenticate() {
+        this.assertCredentials();
         await this.credentials.authenticate();
     }
 }

package/dist/esm-browser/common/settings.test.js

@@ -1,4 +1,5 @@
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { ApiKey } from '../authentication/apikey.js';
 import { env } from './env.js';
 describe('Settings.apiVersion', () => {
     beforeEach(() => {
@@ -15,6 +16,14 @@ describe('Settings.apiVersion', () => {
     it('headers include Blaxel-Version set to the default', async () => {
         delete env.BL_API_VERSION;
         const { settings } = await import('./settings.js');
-        expect(settings.headers['Blaxel-Version']).toBe('2026-04-16');
+        // headers now requires resolvable credentials; run in an authenticated context
+        const previous = settings.credentials;
+        settings.credentials = new ApiKey({ apiKey: 'test-key', workspace: 'test-ws' });
+        try {
+            expect(settings.headers['Blaxel-Version']).toBe('2026-04-16');
+        }
+        finally {
+            settings.credentials = previous;
+        }
     });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@blaxel/core",
-	"version": "0.2.87-preview.169",
+	"version": "0.2.87-preview.171",
 	"description": "Blaxel Core SDK for TypeScript",
 	"license": "MIT",
 	"author": "Blaxel, INC (https://blaxel.ai)",