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

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Credentials = void 0;
+exports.MissingCredentials = exports.Credentials = void 0;
 const env_js_1 = require("../common/env.js");
 class Credentials {
     async authenticate() { }
@@ -15,3 +15,13 @@ class Credentials {
     }
 }
 exports.Credentials = Credentials;
+/**
+ * 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`).
+ */
+class MissingCredentials extends Credentials {
+}
+exports.MissingCredentials = MissingCredentials;

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

@@ -51,7 +51,9 @@ function getCredentials() {
 function authentication() {
     const credentials = getCredentials();
     if (!credentials) {
-        return new credentials_js_1.Credentials();
+        // Never silently fall back to empty headers: a marker that triggers a
+        // clear CredentialsError when an authenticated request is attempted.
+        return new credentials_js_1.MissingCredentials();
     }
     if (credentials.apiKey) {
         return new apikey_js_1.ApiKey(credentials);

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

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const apikey_js_1 = require("../authentication/apikey.js");
+const credentials_js_1 = require("../authentication/credentials.js");
+const index_js_1 = require("../authentication/index.js");
+const errors_js_1 = require("./errors.js");
+const settings_js_1 = require("./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.
+ */
+(0, vitest_1.describe)('credential validation', () => {
+    const AUTH_ENV = ['BL_API_KEY', 'BL_WORKSPACE', 'BL_CLIENT_CREDENTIALS'];
+    let savedEnv;
+    let savedCredentials;
+    let savedConfig;
+    (0, vitest_1.beforeEach)(() => {
+        savedEnv = {};
+        for (const key of AUTH_ENV) {
+            savedEnv[key] = process.env[key];
+            delete process.env[key];
+        }
+        savedCredentials = settings_js_1.settings.credentials;
+        savedConfig = settings_js_1.settings.config;
+        settings_js_1.settings.config = { proxy: '', apikey: '', workspace: '' };
+    });
+    (0, vitest_1.afterEach)(() => {
+        for (const key of AUTH_ENV) {
+            if (savedEnv[key] === undefined)
+                delete process.env[key];
+            else
+                process.env[key] = savedEnv[key];
+        }
+        settings_js_1.settings.credentials = savedCredentials;
+        settings_js_1.settings.config = savedConfig;
+    });
+    (0, vitest_1.it)('API key without workspace throws a clear BL_WORKSPACE error from headers', () => {
+        settings_js_1.settings.credentials = new apikey_js_1.ApiKey({ apiKey: 'test-key' });
+        (0, vitest_1.expect)(() => settings_js_1.settings.headers).toThrow(errors_js_1.CredentialsError);
+        (0, vitest_1.expect)(() => settings_js_1.settings.headers).toThrow(/BL_WORKSPACE/);
+    });
+    (0, vitest_1.it)('API key without workspace rejects from authenticate()', async () => {
+        settings_js_1.settings.credentials = new apikey_js_1.ApiKey({ apiKey: 'test-key' });
+        await (0, vitest_1.expect)(settings_js_1.settings.authenticate()).rejects.toThrow(/BL_WORKSPACE/);
+    });
+    (0, vitest_1.it)('workspace set but no API key names the missing API key', () => {
+        process.env.BL_WORKSPACE = 'my-workspace';
+        settings_js_1.settings.credentials = new credentials_js_1.MissingCredentials();
+        (0, vitest_1.expect)(() => settings_js_1.settings.headers).toThrow(/API key is missing/);
+    });
+    (0, vitest_1.it)('no credentials at all names both env vars', () => {
+        settings_js_1.settings.credentials = new credentials_js_1.MissingCredentials();
+        (0, vitest_1.expect)(() => settings_js_1.settings.headers).toThrow(errors_js_1.CredentialsError);
+        (0, vitest_1.expect)(() => settings_js_1.settings.headers).toThrow(/BL_API_KEY and BL_WORKSPACE/);
+    });
+    (0, vitest_1.it)('api key + workspace builds clean headers with no empty values', () => {
+        settings_js_1.settings.credentials = new apikey_js_1.ApiKey({ apiKey: 'test-key', workspace: 'my-workspace' });
+        const headers = settings_js_1.settings.headers;
+        (0, vitest_1.expect)(headers['x-blaxel-workspace']).toBe('my-workspace');
+        (0, vitest_1.expect)(headers['x-blaxel-authorization']).toBe('Bearer test-key');
+        (0, vitest_1.expect)(Object.values(headers)).not.toContain('');
+    });
+    (0, vitest_1.it)('authentication() returns a real ApiKey when BL_API_KEY is set', () => {
+        process.env.BL_API_KEY = 'test-key';
+        (0, vitest_1.expect)((0, index_js_1.authentication)()).toBeInstanceOf(apikey_js_1.ApiKey);
+    });
+});

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

@@ -1,6 +1,21 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.CredentialsError = void 0;
 exports.handleDynamicImportError = handleDynamicImportError;
+/**
+ * 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".
+ */
+class CredentialsError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CredentialsError";
+    }
+}
+exports.CredentialsError = CredentialsError;
 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/cjs-browser/common/settings.js

@@ -7,12 +7,29 @@ exports.settings = void 0;
 const yaml_1 = __importDefault(require("yaml"));
 const apikey_js_1 = require("../authentication/apikey.js");
 const clientcredentials_js_1 = require("../authentication/clientcredentials.js");
+const credentials_js_1 = require("../authentication/credentials.js");
 const index_js_1 = require("../authentication/index.js");
 const env_js_1 = require("../common/env.js");
+const errors_js_1 = require("../common/errors.js");
 const node_js_1 = require("../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_js_1.env.BL_WORKSPACE;
+    const hasApiKey = !!env_js_1.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
@@ -173,6 +190,7 @@ class Settings {
         return env_js_1.env.BL_API_VERSION || BLAXEL_API_VERSION;
     }
     get headers() {
+        this.assertCredentials();
         const osArch = getOsArch();
         return {
             "x-blaxel-authorization": this.authorization,
@@ -258,7 +276,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 credentials_js_1.MissingCredentials) {
+            throw new errors_js_1.CredentialsError(missingCredentialsMessage());
+        }
+        if (!this.workspace) {
+            throw new errors_js_1.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/cjs-browser/common/settings.test.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 const vitest_1 = require("vitest");
+const apikey_js_1 = require("../authentication/apikey.js");
 const env_js_1 = require("./env.js");
 (0, vitest_1.describe)('Settings.apiVersion', () => {
     (0, vitest_1.beforeEach)(() => {
@@ -50,6 +51,14 @@ const env_js_1 = require("./env.js");
     (0, vitest_1.it)('headers include Blaxel-Version set to the default', async () => {
         delete env_js_1.env.BL_API_VERSION;
         const { settings } = await Promise.resolve().then(() => __importStar(require('./settings.js')));
-        (0, vitest_1.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_js_1.ApiKey({ apiKey: 'test-key', workspace: 'test-ws' });
+        try {
+            (0, vitest_1.expect)(settings.headers['Blaxel-Version']).toBe('2026-04-16');
+        }
+        finally {
+            settings.credentials = previous;
+        }
     });
 });

package/dist/cjs-browser/types/authentication/credentials.d.ts

@@ -4,3 +4,12 @@ export declare class Credentials {
     get authorization(): string;
     get token(): string;
 }
+/**
+ * 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 declare class MissingCredentials extends Credentials {
+}

package/dist/cjs-browser/types/common/credentials.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cjs-browser/types/common/errors.d.ts

@@ -1 +1,11 @@
+/**
+ * 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 declare class CredentialsError extends Error {
+    constructor(message: string);
+}
 export declare function handleDynamicImportError(err: any): void;

package/dist/cjs-browser/types/common/h2fetch.d.ts

@@ -10,13 +10,18 @@ import type { H2Pool } from "./h2pool.js";
  */
 export declare function createH2Fetch(session: http2.ClientHttp2Session): (input: Request) => Promise<Response>;
 /**
- * Creates a fetch()-compatible function backed by the H2 session pool.
+ * Creates a fetch()-compatible function backed by the H2 session pool, routed
+ * through the single gateway. Used as the generated client's `fetch`.
  *
- * The pool validates idle sessions before reuse. If no usable H2 session is
- * available, the request falls back to regular fetch before any H2 frames
- * are sent.
+ * If no usable H2 session is available, the request falls back to regular fetch
+ * before any H2 frames are sent.
  */
 export declare function createPoolBackedH2Fetch(pool: H2Pool, domain: string): (input: Request) => Promise<Response>;
+/**
+ * Pool-backed H2 request taking raw url + init (skips Request allocation),
+ * routed through the same single gateway. Used by `SandboxAction.h2Fetch` and
+ * the code interpreter.
+ */
 export declare function h2RequestDirectFromPool(pool: H2Pool, domain: string, url: string, init?: RequestInit): Promise<Response>;
 /**
  * Low-level H2 request that takes raw URL + init, skipping Request construction.

package/dist/cjs-browser/types/common/settings.d.ts

@@ -63,6 +63,15 @@ declare class Settings {
     get disableH2(): boolean;
     get maxConcurrentH2Requests(): number;
     get fsPartRetries(): number;
+    /**
+     * 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.
+     */
+    private assertCredentials;
     authenticate(): Promise<void>;
 }
 export declare const settings: Settings;