From 20c404f45439f686e6f10333796be6b48768b86e Mon Sep 17 00:00:00 2001 From: Shri Sukhani <25730420+shrisukhani@users.noreply.github.com> Date: Tue, 10 Nov 2026 00:50:18 +0000 Subject: [PATCH 1/4] Fix uploadFile stream error handling, public type exports, and SDK parity --- src/customer-key.ts | 39 +++++++++--- src/services/base.ts | 9 ++- src/services/sandboxes.ts | 16 ++--- src/services/secrets.ts | 8 ++- src/services/sessions.ts | 42 ++++++++++--- src/services/vaults.ts | 3 +- src/tools/index.ts | 9 +-- src/types/index.ts | 17 ++++++ src/types/session.ts | 3 + tests/unit/customer-secrets.test.ts | 49 +++++++++++++-- tests/unit/public-types-contract.test.ts | 44 +++++++++++++ tests/unit/sandbox-secrets.test.ts | 17 ++++-- .../session-web-bot-auth-proxy-routes.test.ts | 61 ++++++++++++++++++- 13 files changed, 272 insertions(+), 45 deletions(-) diff --git a/src/customer-key.ts b/src/customer-key.ts index 0e6b134..6b566e1 100644 --- a/src/customer-key.ts +++ b/src/customer-key.ts @@ -463,6 +463,36 @@ export const assertCustomerKey = (key: unknown, what = "customerKey"): CustomerK return candidate; }; +/** @internal Checks that `keys` is a CustomerKey or a non-empty list of them before anything is sent. */ +export const assertCustomerKeys = (keys: unknown, what = "customerKey"): readonly CustomerKey[] => { + if (!Array.isArray(keys)) { + return [assertCustomerKey(keys, what)]; + } + if (keys.length === 0) { + throw new HyperbrowserError(`Pass at least one customer key as ${what}`, { + code: "invalid_request", + retryable: false, + }); + } + return keys.map((key, index) => assertCustomerKey(key, `${what}[${index}]`)); +}; + +/** @internal Wraps `innerEnvelope` and checks that `wrap()` returned a non-empty string. */ +export const wrapEnvelope = async ( + customerKey: CustomerKey, + innerEnvelope: string, + encryptionContext: string +): Promise => { + const envelope = await customerKey.wrap(innerEnvelope, encryptionContext); + if (typeof envelope !== "string" || !envelope) { + throw new HyperbrowserError("The customer key's wrap() must return the envelope as a string", { + code: "invalid_request", + retryable: false, + }); + } + return envelope; +}; + /** * @internal Unwrap a wrapped version with the key among `keys` that wrapped * it, and check the result is the inner envelope the version holds. @@ -489,14 +519,7 @@ export const customerKeyFor = ( kid: string, label: string ): CustomerKey => { - const list = (Array.isArray(keys) ? keys : [keys]) as readonly CustomerKey[]; - if (list.length === 0) { - throw new HyperbrowserError("Pass at least one customer key", { - code: "invalid_request", - retryable: false, - }); - } - list.forEach((key, index) => assertCustomerKey(key, `customerKey[${index}]`)); + const list = assertCustomerKeys(keys); const key = list.find((candidate) => candidate.kid === kid); if (!key) { throw new HyperbrowserError( diff --git a/src/services/base.ts b/src/services/base.ts index 6fc2223..95702eb 100644 --- a/src/services/base.ts +++ b/src/services/base.ts @@ -21,7 +21,14 @@ const getRequestId = (response: Response): string | undefined => { const SERVER_ERROR_CODE_PATTERN = /^[A-Z][A-Z0-9]*(_[A-Z0-9]+)+$/; /** Codes whose retryable status default (such as 503) would be wrong. */ -const NON_RETRYABLE_ERROR_CODES = new Set(["SECRETS_NOT_CONFIGURED"]); +const NON_RETRYABLE_ERROR_CODES = new Set([ + "SECRETS_ADMIN_REQUIRED", + "SECRETS_NOT_CONFIGURED", + "SECRET_KEY_UNAVAILABLE", + "SECRET_DECRYPT_FAILED", + "SECRET_ENVELOPE_INVALID", + "SECRET_VALUE_INVALID", +]); /** The sandbox and secret an error is about, when the API names them. */ const errorMessageContext = (errorData: { diff --git a/src/services/sandboxes.ts b/src/services/sandboxes.ts index 7d23166..b5827cc 100644 --- a/src/services/sandboxes.ts +++ b/src/services/sandboxes.ts @@ -427,6 +427,10 @@ export class SandboxHandle { return (this.detail.exposedPorts ?? []).map((entry) => ({ ...entry })); } + get startupSecrets(): SandboxDetail["startupSecrets"] { + return this.detail.startupSecrets; + } + toJSON(): SandboxDetail { return { ...this.detail }; } @@ -592,18 +596,6 @@ export class SandboxHandle { return { ...this.runtimeSession }; } - private applyRuntimeSession(session: SandboxRuntimeState) { - this.runtimeSession = { ...session }; - this.detail = { - ...this.detail, - status: session.status, - region: session.region, - runtime: session.runtime, - token: session.token, - tokenExpiresAt: session.tokenExpiresAt, - }; - } - private clearRuntimeSession(status: SandboxDetail["status"] = this.detail.status) { this.runtimeSession = null; this.detail = { diff --git a/src/services/secrets.ts b/src/services/secrets.ts index 15f13f2..245d445 100644 --- a/src/services/secrets.ts +++ b/src/services/secrets.ts @@ -1,8 +1,10 @@ import { assertCustomerKey, + assertCustomerKeys, CustomerKey, secretEnvelopeDigest, unwrapVersion, + wrapEnvelope, } from "../customer-key"; import { HyperbrowserError, invalidRequest } from "../error"; import { MAX_SECRET_VERSION, SECRET_NAME_PATTERN } from "../sandbox/secret-references"; @@ -280,6 +282,7 @@ export class SecretsService extends BaseService { ): Promise { const version = options?.version ?? "latest"; assertVersion(version, true); + assertCustomerKeys(customerKey); try { const resolved = await this.resolve(secret); const wrapped = await this.fetchWrapped(resolved.id, version); @@ -302,6 +305,7 @@ export class SecretsService extends BaseService { */ async rewrap(secret: string, params: RewrapSecretParams): Promise { const { from, to, versions } = params ?? ({} as RewrapSecretParams); + assertCustomerKeys(from, "from"); assertCustomerKey(to, "to"); if (versions !== undefined) { if (!Array.isArray(versions)) @@ -321,7 +325,7 @@ export class SecretsService extends BaseService { const wrapped = await this.fetchWrapped(detail.id, version); const label = `Version ${version} of secret ${detail.name}`; const inner = await unwrapVersion(wrapped, from, label); - const envelope = await to.wrap(inner, detail.encryptionContext); + const envelope = await wrapEnvelope(to, inner, detail.encryptionContext); rewrapped.push( await this.putWrapping(detail.id, version, { envelope, innerDigest: wrapped.innerDigest }) ); @@ -417,7 +421,7 @@ export class SecretsService extends BaseService { customerKey === undefined ? { envelope: inner } : { - envelope: await customerKey.wrap(inner, secret.encryptionContext), + envelope: await wrapEnvelope(customerKey, inner, secret.encryptionContext), innerDigest: secretEnvelopeDigest(inner), innerKid: sealer.kid, }; diff --git a/src/services/sessions.ts b/src/services/sessions.ts index 9d87fc1..fb21635 100644 --- a/src/services/sessions.ts +++ b/src/services/sessions.ts @@ -1,4 +1,4 @@ -import { promises as fs, Stats, createReadStream, ReadStream } from "fs"; +import { promises as fs, constants as fsConstants, Stats, createReadStream, ReadStream } from "fs"; import * as path from "path"; import FormData from "form-data"; import { RequestInit } from "node-fetch"; @@ -261,13 +261,18 @@ export class SessionsService extends BaseService { async uploadFile(id: string, fileOptions: UploadFileOptions): Promise { const { fileInput, fileName } = fileOptions; + let fileStream: ReadStream | undefined; + let streamError: HyperbrowserError | undefined; + try { let fetchOptions: RequestInit; + let streamFailure: Promise | undefined; if (typeof fileInput === "string") { let stats: Stats; try { stats = await fs.stat(fileInput); + await fs.access(fileInput, fsConstants.R_OK); } catch (error: any) { if (error.code === "ENOENT") { throw new HyperbrowserError(`File not found: ${fileInput}`, undefined); @@ -289,15 +294,27 @@ export class SessionsService extends BaseService { } const formData = new FormData(); - const fileStream = createReadStream(fileInput); + fileStream = createReadStream(fileInput); const fileBaseName = fileName || path.basename(fileInput); - fileStream.on("error", (error) => { - throw new HyperbrowserError( - `Failed to read file ${fileInput}: ${error.message}`, - undefined - ); + let rejectStreamError: ((error: HyperbrowserError) => void) | undefined; + streamFailure = new Promise((_, reject) => { + rejectStreamError = reject; }); + streamFailure.catch(() => {}); + + const onStreamError = (error: Error) => { + if (!streamError) { + streamError = new HyperbrowserError( + `Failed to read file at ${fileInput}: ${error.message}`, + undefined + ); + } + rejectStreamError?.(streamError); + }; + + fileStream.on("error", onStreamError); + formData.on("error", onStreamError); formData.append("file", fileStream, { filename: fileBaseName, @@ -347,13 +364,22 @@ export class SessionsService extends BaseService { ); } - return await this.request(`/session/${id}/uploads`, fetchOptions); + const requestPromise = this.request( + `/session/${id}/uploads`, + fetchOptions + ); + return await (streamFailure ? Promise.race([requestPromise, streamFailure]) : requestPromise); } catch (error) { + if (streamError) { + throw streamError; + } if (error instanceof HyperbrowserError) { throw error; } throw new HyperbrowserError(`Failed to upload file for session ${id}: ${error}`, undefined); + } finally { + fileStream?.destroy(); } } diff --git a/src/services/vaults.ts b/src/services/vaults.ts index 3f1343d..68db82e 100644 --- a/src/services/vaults.ts +++ b/src/services/vaults.ts @@ -1,4 +1,4 @@ -import { CustomerKey, unwrapVersion } from "../customer-key"; +import { assertCustomerKeys, CustomerKey, unwrapVersion } from "../customer-key"; import { HyperbrowserError, invalidRequest } from "../error"; import { CreateVaultParams, @@ -94,6 +94,7 @@ export class VaultsService extends BaseService { vault: string, customerKey: CustomerKey | readonly CustomerKey[] ): Promise { + assertCustomerKeys(customerKey); const wrapped = await this.getWrapped(vault); const unwrapped: VaultReference["unwrapped"] = {}; for (const [env, entry] of Object.entries(wrapped.entries ?? {})) { diff --git a/src/tools/index.ts b/src/tools/index.ts index 13d8744..d0f945c 100644 --- a/src/tools/index.ts +++ b/src/tools/index.ts @@ -90,10 +90,11 @@ export class WebsiteExtractTool { static anthropicToolDefinition = EXTRACT_TOOL_ANTHROPIC; static async runnable(hb: HyperbrowserClient, params: StartExtractJobParams): Promise { - if (params.schema && typeof params.schema === "string") { - params.schema = JSON.parse(params.schema); - } - const resp = await hb.extract.startAndWait(params); + const requestParams: StartExtractJobParams = + params.schema && typeof params.schema === "string" + ? { ...params, schema: JSON.parse(params.schema) } + : { ...params }; + const resp = await hb.extract.startAndWait(requestParams); return resp.data ? JSON.stringify(resp.data) : ""; } } diff --git a/src/types/index.ts b/src/types/index.ts index f011472..7e45485 100644 --- a/src/types/index.ts +++ b/src/types/index.ts @@ -15,7 +15,13 @@ export { ScrapeJobResponse, ScrapeOptions, ScrapeJobStatusResponse, + StartBatchScrapeJobParams, + StartBatchScrapeJobResponse, BatchScrapeJobStatusResponse, + BatchScrapeJobResponse, + GetBatchScrapeJobParams, + ScrapedPage, + ScreenshotOptions, StorageStateOptions, } from "./scrape"; export { @@ -136,6 +142,7 @@ export { SessionListParams, SessionListResponse, ScreenConfig, + CreateSessionProfile, CaptchaEvaluationPageResult, CaptchaEvaluationParams, CaptchaEvaluationResponse, @@ -144,6 +151,7 @@ export { CaptchaSolverType, CreateSessionParams, CreateSessionSnapshotResponse, + SessionRecording, GetSessionDownloadsUrlResponse, GetSessionVideoRecordingUrlResponse, GetSessionRecordingUrlResponse, @@ -427,6 +435,15 @@ export { BatchFetchJobResponse, BatchFetchJobStatus, } from "./web/batch-fetch"; +export { + WebCrawlJobStatus, + WebCrawlOptions, + StartWebCrawlJobParams, + GetWebCrawlJobParams, + StartWebCrawlJobResponse, + WebCrawlJobStatusResponse, + WebCrawlJobResponse, +} from "./web/crawl"; export { WebSearchParams, WebSearchResponse, diff --git a/src/types/session.ts b/src/types/session.ts index 2568f6d..6215d70 100644 --- a/src/types/session.ts +++ b/src/types/session.ts @@ -22,6 +22,7 @@ export interface BasicResponse { export interface SessionProfile { id: string; persistChanges?: boolean; + persistNetworkCache?: boolean; } /** How a session signs its requests with Web Bot Auth. */ @@ -83,6 +84,8 @@ export interface Session { launchState?: SessionLaunchState | null; creditsUsed: number | null; creditBreakdown: SessionCreditBreakdown; + duration?: number; + proxyDataConsumed?: string; } export interface SessionDetail extends Session { diff --git a/tests/unit/customer-secrets.test.ts b/tests/unit/customer-secrets.test.ts index 24e8754..8bc8243 100644 --- a/tests/unit/customer-secrets.test.ts +++ b/tests/unit/customer-secrets.test.ts @@ -337,7 +337,7 @@ describe("customer-protected secrets", () => { test("unwrap refuses a key that didn't wrap the version, and a digest mismatch", async () => { let stored: WrappedSecretVersion = storedVersion("hunter2", rsaKey); - const { service } = mockService(secrets(), (_method, path) => + const { service, calls } = mockService(secrets(), (_method, path) => path.endsWith("/wrapped") ? stored : { ...secret(), versions: [] } ); await expect(service.unwrap(ID, ecKey)).rejects.toMatchObject({ @@ -345,7 +345,12 @@ describe("customer-protected secrets", () => { }); stored = { ...stored, innerDigest: secretEnvelopeDigest("something else") }; await expect(service.unwrap(ID, rsaKey)).rejects.toThrow(/doesn't match its innerDigest/); + const callsBeforeInvalidKey = calls().length; await expect(service.unwrap(ID, [])).rejects.toThrow(/at least one customer key/); + await expect(service.unwrap(ID, {} as CustomerKey)).rejects.toMatchObject({ + code: "invalid_request", + }); + expect(calls()).toHaveLength(callsBeforeInvalidKey); }); test("getWrappedVersion fetches a version's outer envelope", async () => { @@ -400,12 +405,20 @@ describe("customer-protected secrets", () => { expect(ecKey.unwrap(puts[1].envelope)).toBe(v1.inner); }); - test("rewrap refuses platform secrets, and replaceVersionWrapping sends the envelope as given", async () => { + test("rewrap refuses platform secrets, validates keys upfront, and checks wrap() output", async () => { const { service, calls, bodies } = mockService(secrets(), (method, path) => { if (path === `/secrets/${ID}`) return { ...secret({ protection: "platform" }), versions: [] }; if (method === "PUT") return storedVersion("x", ecKey, 5); throw new Error(`unexpected ${path}`); }); + await expect(service.rewrap(ID, { from: [] as any, to: ecKey })).rejects.toMatchObject({ + code: "invalid_request", + }); + await expect(service.rewrap(ID, { from: {} as CustomerKey, to: ecKey })).rejects.toMatchObject({ + code: "invalid_request", + }); + expect(calls()).toEqual([]); + await expect(service.rewrap(ID, { from: rsaKey, to: ecKey })).rejects.toThrow( /not customer-protected/ ); @@ -419,6 +432,28 @@ describe("customer-protected secrets", () => { await expect( service.replaceVersionWrapping(ID, 5, { envelope: "", innerDigest: "digest" }) ).rejects.toMatchObject({ code: "invalid_request" }); + + const brokenWrapKey: CustomerKey = { + kid: "broken", + wrap: () => "", + unwrap: (env) => env, + }; + const v1 = storedVersion("one", rsaKey, 1); + const { service: rewrapService } = mockService(secrets(), (_method, path) => { + if (path === `/secrets/${ID}`) { + return { + ...secret({ latestVersion: 1 }), + versions: [{ version: 1, kid: v1.kid, outerKid: v1.outerKid }], + }; + } + if (path === `/secrets/${ID}/versions/1/wrapped`) return v1; + throw new Error(`unexpected ${path}`); + }); + await expect( + rewrapService.rewrap(ID, { from: rsaKey, to: brokenWrapKey }) + ).rejects.toMatchObject({ + code: "invalid_request", + }); }); test("version details keep outerKid and retiresAt", async () => { @@ -477,9 +512,9 @@ describe("customer-protected vaults", () => { expect(calls()).toEqual([`GET /vaults/${VAULT_ID}`, `GET /vaults/${VAULT_ID}/wrapped`]); }); - test("unwrap names the entry whose key is missing", async () => { + test("unwrap names the entry whose key is missing and validates keys before fetching", async () => { const stored = storedVersion("hunter2", ecKey, 7); - const { service } = mockService(vaults(), (_method, path) => + const { service, calls } = mockService(vaults(), (_method, path) => path.endsWith("/wrapped") ? { id: VAULT_ID, @@ -488,6 +523,12 @@ describe("customer-protected vaults", () => { } : vault ); + await expect(service.unwrap(VAULT_ID, [])).rejects.toMatchObject({ code: "invalid_request" }); + await expect(service.unwrap(VAULT_ID, {} as CustomerKey)).rejects.toMatchObject({ + code: "invalid_request", + }); + expect(calls()).toEqual([]); + const error = await service.unwrap(VAULT_ID, rsaKey).catch((e) => e); expect(error).toBeInstanceOf(HyperbrowserError); expect(error).toMatchObject({ code: "customer_key_mismatch" }); diff --git a/tests/unit/public-types-contract.test.ts b/tests/unit/public-types-contract.test.ts index edf750e..deb6139 100644 --- a/tests/unit/public-types-contract.test.ts +++ b/tests/unit/public-types-contract.test.ts @@ -1,5 +1,6 @@ import { describe, expect, expectTypeOf, test } from "vitest"; import type { + BatchScrapeJobResponse, ClickActionParams, DragActionParams, ScrollActionParams, @@ -11,6 +12,9 @@ import type { ComputerActionResponseDataCursorPosition, CompleteSandboxImageBuildParams, CreateSandboxImageBuildParams, + CreateSessionProfile, + GetBatchScrapeJobParams, + GetWebCrawlJobParams, Sandbox, SandboxExecParams, SandboxImageBuildInputFormat, @@ -21,9 +25,22 @@ import type { SandboxNetworkPolicy, SandboxSnapshotListResponse, SandboxSnapshotSummary, + ScrapedPage, + ScreenshotOptions, + Session, + SessionProfile, + SessionRecording, SessionRegion, SessionStatus, + StartBatchScrapeJobParams, + StartBatchScrapeJobResponse, + StartWebCrawlJobParams, + StartWebCrawlJobResponse, VolumeListResponse, + WebCrawlJobResponse, + WebCrawlJobStatus, + WebCrawlJobStatusResponse, + WebCrawlOptions, } from "../../src/types"; import { ComputerAction } from "../../src/types"; import { ComputerActionService } from "../../src/services/computer-action"; @@ -183,4 +200,31 @@ describe("public type compatibility", () => { expectTypeOf<"BUILDING">().not.toExtend(); expectTypeOf<"canceled">().toExtend(); }); + + test("exports web crawl, batch scrape, and session types from root types barrel", () => { + expectTypeOf().toEqualTypeOf< + "pending" | "running" | "completed" | "failed" + >(); + expectTypeOf().toEqualTypeOf< + WebCrawlOptions | undefined + >(); + expectTypeOf().toEqualTypeOf(); + expectTypeOf().toEqualTypeOf(); + expectTypeOf().toEqualTypeOf(); + expectTypeOf().toEqualTypeOf(); + + expectTypeOf().toEqualTypeOf(); + expectTypeOf().toEqualTypeOf(); + expectTypeOf().toEqualTypeOf(); + expectTypeOf().toEqualTypeOf(); + expectTypeOf().toEqualTypeOf(); + + expectTypeOf().toEqualTypeOf(); + expectTypeOf().toEqualTypeOf< + boolean | undefined + >(); + expectTypeOf().toEqualTypeOf(); + expectTypeOf().toEqualTypeOf(); + expectTypeOf().toEqualTypeOf(); + }); }); diff --git a/tests/unit/sandbox-secrets.test.ts b/tests/unit/sandbox-secrets.test.ts index 1fd5ec7..e53c145 100644 --- a/tests/unit/sandbox-secrets.test.ts +++ b/tests/unit/sandbox-secrets.test.ts @@ -473,6 +473,7 @@ describe("vaults in sandboxes", () => { vault: "app-env", secrets: { API_KEY: { name: "provider-key" } }, }); + expect(sandbox.startupSecrets).toEqual(vaultBindings); expect(sandbox.toJSON().startupSecrets).toEqual(vaultBindings); }); @@ -483,6 +484,7 @@ describe("vaults in sandboxes", () => { .mockResolvedValueOnce({ ...wireDetail, status: "active" }); const sandbox = await service.create({ imageName: "node", vault: "app-env" }); await sandbox.info(); + expect(sandbox.startupSecrets).toEqual(vaultBindings); expect(sandbox.toJSON().startupSecrets).toEqual(vaultBindings); }); @@ -811,12 +813,19 @@ describe("control API error fields", () => { expect(error.details).toMatchObject({ requiredScopes: ["secrets.use"] }); }); - test("SECRETS_NOT_CONFIGURED is not retried despite its 503", async () => { - respond(503, { code: "SECRETS_NOT_CONFIGURED", message: "not configured" }); + test.each([ + "SECRETS_ADMIN_REQUIRED", + "SECRETS_NOT_CONFIGURED", + "SECRET_KEY_UNAVAILABLE", + "SECRET_DECRYPT_FAILED", + "SECRET_ENVELOPE_INVALID", + "SECRET_VALUE_INVALID", + ])("%s is not retried despite its 503", async (code) => { + respond(503, { code, message: "not retryable" }); const service = new TestService("key", "https://api.example.com", 1_000); await expect(service.post("/x")).rejects.toMatchObject({ statusCode: 503, - code: "SECRETS_NOT_CONFIGURED", + code, retryable: false, }); @@ -825,7 +834,7 @@ describe("control API error fields", () => { return this.request(path); } } - respond(503, { code: "SECRETS_NOT_CONFIGURED", message: "not configured" }); + respond(503, { code, message: "not retryable" }); await expect( new GetService("key", "https://api.example.com", 1_000).get("/secrets/public-key") ).rejects.toMatchObject({ retryable: false }); diff --git a/tests/unit/session-web-bot-auth-proxy-routes.test.ts b/tests/unit/session-web-bot-auth-proxy-routes.test.ts index 07c31a8..fa5a85a 100644 --- a/tests/unit/session-web-bot-auth-proxy-routes.test.ts +++ b/tests/unit/session-web-bot-auth-proxy-routes.test.ts @@ -1,3 +1,6 @@ +import fs from "fs"; +import os from "os"; +import path from "path"; import { afterEach, expect, expectTypeOf, test, vi } from "vitest"; import { Response } from "node-fetch"; @@ -7,7 +10,8 @@ vi.mock("node-fetch", async () => { return { ...actual, default: (...args: unknown[]) => fetchMock(...args) }; }); -import { HyperbrowserClient as Hyperbrowser } from "../../src/client"; +import { HyperbrowserClient as Hyperbrowser, HyperbrowserError } from "../../src/client"; +import { WebsiteExtractTool } from "../../src/tools"; import type { CreateSessionParams, ProxyRoute, @@ -72,3 +76,58 @@ test("public types describe the options and the signing launch state", () => { onlyDomains?: string[]; }>(); }); + +test("uploadFile rejects with HyperbrowserError for a non-existent file path and on stream errors without crashing", async () => { + const sdk = client(); + const missingPath = path.join(os.tmpdir(), `hb-missing-${Date.now()}-${Math.random()}.txt`); + + await expect( + sdk.sessions.uploadFile("session-1", { fileInput: missingPath }) + ).rejects.toThrowError(HyperbrowserError); + expect(fetchMock).not.toHaveBeenCalled(); + + const tempFile = path.join(os.tmpdir(), `hb-upload-${Date.now()}-${Math.random()}.txt`); + fs.writeFileSync(tempFile, "hello"); + try { + fetchMock.mockImplementationOnce(async (_url: string, init: { body?: any }) => { + // Simulate a stream error after fs.stat/fs.access succeed while the request is in flight + const streams = (init?.body?._streams ?? []).filter( + (entry: unknown) => + entry && typeof entry === "object" && typeof (entry as any).emit === "function" + ); + if (streams[0]) { + streams[0].emit("error", new Error("disk read failure")); + } + await new Promise((resolve) => setTimeout(resolve, 50)); + return respond({ message: "uploaded" }); + }); + + await expect( + sdk.sessions.uploadFile("session-1", { fileInput: tempFile }) + ).rejects.toThrowError( + new HyperbrowserError(`Failed to read file at ${tempFile}: disk read failure`, undefined) + ); + } finally { + fs.rmSync(tempFile, { force: true }); + } +}); + +test("WebsiteExtractTool.runnable parses a JSON string schema without mutating the caller's params", async () => { + const sdk = client(); + const startAndWaitSpy = vi + .spyOn(sdk.extract, "startAndWait") + .mockResolvedValue({ jobId: "ext-1", status: "completed", data: { title: "Example" } }); + + const params = { + urls: ["https://example.com"], + schema: '{"type":"object","properties":{"title":{"type":"string"}}}', + }; + + const result = await WebsiteExtractTool.runnable(sdk, params); + expect(result).toBe('{"title":"Example"}'); + expect(params.schema).toBe('{"type":"object","properties":{"title":{"type":"string"}}}'); + expect(startAndWaitSpy).toHaveBeenCalledWith({ + urls: ["https://example.com"], + schema: { type: "object", properties: { title: { type: "string" } } }, + }); +}); From 2c39ae2784da3ed9e5f74f0145c1fb244a0879c9 Mon Sep 17 00:00:00 2001 From: Shri Sukhani <25730420+shrisukhani@users.noreply.github.com> Date: Tue, 10 Nov 2026 04:05:08 +0000 Subject: [PATCH 2/4] fix(types): add enableWebglFingerprinting to SessionLaunchState --- src/types/session.ts | 1 + 1 file changed, 1 insertion(+) diff --git a/src/types/session.ts b/src/types/session.ts index 6215d70..ec14ef9 100644 --- a/src/types/session.ts +++ b/src/types/session.ts @@ -64,6 +64,7 @@ export interface SessionLaunchState { enableAlwaysOpenPdfExternally?: boolean; appendTimestampToDownloads?: boolean; disablePostQuantumKeyAgreement?: boolean; + enableWebglFingerprinting?: boolean; } export interface SessionCreditBreakdown { From 67b8e6b99842184ed3ade46bdd39f734d611a877 Mon Sep 17 00:00:00 2001 From: Ninad Sinha Date: Mon, 9 Nov 2026 22:37:15 -0800 Subject: [PATCH 3/4] Trap upload stream errors for every input type and abort on failure - uploadFile: attach the FormData/stream error listener for path, stream and Buffer inputs (stream inputs could still crash the process), abort the in-flight request when the body fails, and never destroy a stream the caller owns. - Tests pipe the body like node-fetch does, so they reproduce the uncaught exception on the previous code. - Up-front customer key checks still validate each key but allow an empty list; customerKeyFor rejects it only when a key is needed. - startupSecrets returns a copy, like exposedPorts. - Mark enableWebglFingerprinting as deprecated (the server ignores it). Co-Authored-By: Claude Opus 5.5 --- src/customer-key.ts | 16 ++- src/services/sandboxes.ts | 2 +- src/services/secrets.ts | 2 +- src/services/sessions.ts | 116 ++++++++--------- src/services/vaults.ts | 2 +- src/types/session.ts | 2 + tests/unit/customer-secrets.test.ts | 32 ++++- .../session-web-bot-auth-proxy-routes.test.ts | 118 ++++++++++++++---- 8 files changed, 200 insertions(+), 90 deletions(-) diff --git a/src/customer-key.ts b/src/customer-key.ts index 6b566e1..10cc982 100644 --- a/src/customer-key.ts +++ b/src/customer-key.ts @@ -463,12 +463,22 @@ export const assertCustomerKey = (key: unknown, what = "customerKey"): CustomerK return candidate; }; -/** @internal Checks that `keys` is a CustomerKey or a non-empty list of them before anything is sent. */ -export const assertCustomerKeys = (keys: unknown, what = "customerKey"): readonly CustomerKey[] => { +/** + * @internal Checks that `keys` is a CustomerKey or a list of them before + * anything is sent. An empty list passes only with `allowEmpty`: an up-front + * check must not reject a call that never needs a key (an empty vault, or a + * rewrap with nothing to rewrap); `customerKeyFor` still rejects it when a + * key is actually needed. + */ +export const assertCustomerKeys = ( + keys: unknown, + what = "customerKey", + { allowEmpty = false }: { allowEmpty?: boolean } = {} +): readonly CustomerKey[] => { if (!Array.isArray(keys)) { return [assertCustomerKey(keys, what)]; } - if (keys.length === 0) { + if (keys.length === 0 && !allowEmpty) { throw new HyperbrowserError(`Pass at least one customer key as ${what}`, { code: "invalid_request", retryable: false, diff --git a/src/services/sandboxes.ts b/src/services/sandboxes.ts index b5827cc..936b943 100644 --- a/src/services/sandboxes.ts +++ b/src/services/sandboxes.ts @@ -428,7 +428,7 @@ export class SandboxHandle { } get startupSecrets(): SandboxDetail["startupSecrets"] { - return this.detail.startupSecrets; + return this.detail.startupSecrets?.map((entry) => ({ ...entry })); } toJSON(): SandboxDetail { diff --git a/src/services/secrets.ts b/src/services/secrets.ts index 245d445..fec3164 100644 --- a/src/services/secrets.ts +++ b/src/services/secrets.ts @@ -305,7 +305,7 @@ export class SecretsService extends BaseService { */ async rewrap(secret: string, params: RewrapSecretParams): Promise { const { from, to, versions } = params ?? ({} as RewrapSecretParams); - assertCustomerKeys(from, "from"); + assertCustomerKeys(from, "from", { allowEmpty: true }); assertCustomerKey(to, "to"); if (versions !== undefined) { if (!Array.isArray(versions)) diff --git a/src/services/sessions.ts b/src/services/sessions.ts index fb21635..1aeae93 100644 --- a/src/services/sessions.ts +++ b/src/services/sessions.ts @@ -261,12 +261,56 @@ export class SessionsService extends BaseService { async uploadFile(id: string, fileOptions: UploadFileOptions): Promise { const { fileInput, fileName } = fileOptions; - let fileStream: ReadStream | undefined; + // Our own file stream, destroyed when the upload settles. A stream the + // caller passes in stays theirs and is never destroyed here. + let ownedStream: ReadStream | undefined; + let sourceStream: NodeJS.ReadableStream | undefined; let streamError: HyperbrowserError | undefined; + let rejectStreamError: ((error: HyperbrowserError) => void) | undefined; + const streamFailure = new Promise((_, reject) => { + rejectStreamError = reject; + }); + streamFailure.catch(() => {}); + // Aborts the in-flight request when the body fails, so the socket is not + // held open until the request timeout. + const controller = new AbortController(); + let readLabel = ""; + + // form-data re-emits a source stream's "error" on the FormData, and + // node-fetch pipes the body without an error listener, so an unlistened + // FormData error is thrown as an uncaught exception. Every FormData body + // therefore gets a listener, whatever the input type. + const onStreamError = (error: Error) => { + if (!streamError) { + streamError = new HyperbrowserError( + `Failed to read file ${readLabel}: ${error.message}`, + undefined + ); + } + controller.abort(); + rejectStreamError?.(streamError); + }; + const buildBody = ( + file: NodeJS.ReadableStream | Buffer, + filename: string + ): RequestInit => { + const formData = new FormData(); + formData.on("error", onStreamError); + if (!Buffer.isBuffer(file)) { + sourceStream = file; + file.on("error", onStreamError); + } + formData.append("file", file, { filename }); + return { + method: "POST", + body: formData, + headers: formData.getHeaders(), + signal: controller.signal, + }; + }; try { let fetchOptions: RequestInit; - let streamFailure: Promise | undefined; if (typeof fileInput === "string") { let stats: Stats; @@ -293,70 +337,24 @@ export class SessionsService extends BaseService { throw new HyperbrowserError(`Path is not a file: ${fileInput}`, undefined); } - const formData = new FormData(); - fileStream = createReadStream(fileInput); - const fileBaseName = fileName || path.basename(fileInput); - - let rejectStreamError: ((error: HyperbrowserError) => void) | undefined; - streamFailure = new Promise((_, reject) => { - rejectStreamError = reject; - }); - streamFailure.catch(() => {}); - - const onStreamError = (error: Error) => { - if (!streamError) { - streamError = new HyperbrowserError( - `Failed to read file at ${fileInput}: ${error.message}`, - undefined - ); - } - rejectStreamError?.(streamError); - }; - - fileStream.on("error", onStreamError); - formData.on("error", onStreamError); - - formData.append("file", fileStream, { - filename: fileBaseName, - }); - - fetchOptions = { - method: "POST", - body: formData, - headers: formData.getHeaders(), - }; + readLabel = `at ${fileInput}`; + ownedStream = createReadStream(fileInput); + fetchOptions = buildBody(ownedStream, fileName || path.basename(fileInput)); } else if (this.isReadableStream(fileInput)) { - const formData = new FormData(); - let tmpFileName = fileName || `file-${Date.now()}`; if (fileInput.path && typeof fileInput.path === "string" && !fileName) { tmpFileName = path.basename(fileInput.path); } - formData.append("file", fileInput, { - filename: tmpFileName, - }); - - fetchOptions = { - method: "POST", - body: formData, - headers: formData.getHeaders(), - }; + readLabel = `stream ${tmpFileName}`; + fetchOptions = buildBody(fileInput, tmpFileName); } else if (Buffer.isBuffer(fileInput)) { if (!fileName) { throw new HyperbrowserError("fileName is required when uploading Buffer data", undefined); } - const formData = new FormData(); - formData.append("file", fileInput, { - filename: fileName, - }); - - fetchOptions = { - method: "POST", - body: formData, - headers: formData.getHeaders(), - }; + readLabel = `buffer ${fileName}`; + fetchOptions = buildBody(fileInput, fileName); } else { throw new HyperbrowserError( "Unsupported file input type. Please provide a file path string, ReadStream, or Buffer.", @@ -368,7 +366,8 @@ export class SessionsService extends BaseService { `/session/${id}/uploads`, fetchOptions ); - return await (streamFailure ? Promise.race([requestPromise, streamFailure]) : requestPromise); + requestPromise.catch(() => {}); + return await Promise.race([requestPromise, streamFailure]); } catch (error) { if (streamError) { throw streamError; @@ -379,7 +378,10 @@ export class SessionsService extends BaseService { throw new HyperbrowserError(`Failed to upload file for session ${id}: ${error}`, undefined); } finally { - fileStream?.destroy(); + if (sourceStream && sourceStream !== ownedStream) { + sourceStream.removeListener("error", onStreamError); + } + ownedStream?.destroy(); } } diff --git a/src/services/vaults.ts b/src/services/vaults.ts index 68db82e..774e74c 100644 --- a/src/services/vaults.ts +++ b/src/services/vaults.ts @@ -94,7 +94,7 @@ export class VaultsService extends BaseService { vault: string, customerKey: CustomerKey | readonly CustomerKey[] ): Promise { - assertCustomerKeys(customerKey); + assertCustomerKeys(customerKey, "customerKey", { allowEmpty: true }); const wrapped = await this.getWrapped(vault); const unwrapped: VaultReference["unwrapped"] = {}; for (const [env, entry] of Object.entries(wrapped.entries ?? {})) { diff --git a/src/types/session.ts b/src/types/session.ts index ec14ef9..d7f4f5b 100644 --- a/src/types/session.ts +++ b/src/types/session.ts @@ -64,6 +64,7 @@ export interface SessionLaunchState { enableAlwaysOpenPdfExternally?: boolean; appendTimestampToDownloads?: boolean; disablePostQuantumKeyAgreement?: boolean; + /** @deprecated Discontinued: WebGL fingerprinting was removed from the browser, and the server ignores this option. Kept so existing code still type-checks. */ enableWebglFingerprinting?: boolean; } @@ -259,6 +260,7 @@ export interface CreateSessionParams { saveDownloads?: boolean; imageCaptchaParams?: Array; timeoutMinutes?: number; + /** @deprecated Discontinued: WebGL fingerprinting was removed from the browser, and the server ignores this option. Kept so existing code still type-checks. */ enableWebglFingerprinting?: boolean; enableWindowManager?: boolean; enableWindowManagerTaskbar?: boolean; diff --git a/tests/unit/customer-secrets.test.ts b/tests/unit/customer-secrets.test.ts index 8bc8243..1bd242b 100644 --- a/tests/unit/customer-secrets.test.ts +++ b/tests/unit/customer-secrets.test.ts @@ -411,24 +411,29 @@ describe("customer-protected secrets", () => { if (method === "PUT") return storedVersion("x", ecKey, 5); throw new Error(`unexpected ${path}`); }); - await expect(service.rewrap(ID, { from: [] as any, to: ecKey })).rejects.toMatchObject({ - code: "invalid_request", - }); await expect(service.rewrap(ID, { from: {} as CustomerKey, to: ecKey })).rejects.toMatchObject({ code: "invalid_request", }); + await expect( + service.rewrap(ID, { from: [rsaKey, {} as CustomerKey], to: ecKey }) + ).rejects.toMatchObject({ code: "invalid_request" }); expect(calls()).toEqual([]); + // An empty `from` list is not rejected up front: a rewrap may need no key. + await expect(service.rewrap(ID, { from: [], to: ecKey })).rejects.toThrow( + /not customer-protected/ + ); await expect(service.rewrap(ID, { from: rsaKey, to: ecKey })).rejects.toThrow( /not customer-protected/ ); await service.replaceVersionWrapping(ID, 5, { envelope: "outer", innerDigest: "digest" }); expect(calls()).toEqual([ + `GET /secrets/${ID}`, `GET /secrets/${ID}`, `GET /secrets/${ID}`, `PUT /secrets/${ID}/versions/5/wrapping`, ]); - expect(bodies()[2]).toEqual({ envelope: "outer", innerDigest: "digest" }); + expect(bodies()[3]).toEqual({ envelope: "outer", innerDigest: "digest" }); await expect( service.replaceVersionWrapping(ID, 5, { envelope: "", innerDigest: "digest" }) ).rejects.toMatchObject({ code: "invalid_request" }); @@ -523,12 +528,17 @@ describe("customer-protected vaults", () => { } : vault ); - await expect(service.unwrap(VAULT_ID, [])).rejects.toMatchObject({ code: "invalid_request" }); await expect(service.unwrap(VAULT_ID, {} as CustomerKey)).rejects.toMatchObject({ code: "invalid_request", }); + await expect(service.unwrap(VAULT_ID, [rsaKey, {} as CustomerKey])).rejects.toMatchObject({ + code: "invalid_request", + }); expect(calls()).toEqual([]); + // An empty list is checked once an entry actually needs a key. + await expect(service.unwrap(VAULT_ID, [])).rejects.toThrow(/at least one customer key/); + const error = await service.unwrap(VAULT_ID, rsaKey).catch((e) => e); expect(error).toBeInstanceOf(HyperbrowserError); expect(error).toMatchObject({ code: "customer_key_mismatch" }); @@ -546,7 +556,17 @@ describe("customer-protected vaults", () => { name: "app-env", unwrapped: {}, }); - expect(calls()).toEqual(["GET /vaults", `GET /vaults/${VAULT_ID}/wrapped`]); + // No entry needs a key, so an empty key list is fine too. + await expect(service.unwrap("app-env", [])).resolves.toEqual({ + name: "app-env", + unwrapped: {}, + }); + expect(calls()).toEqual([ + "GET /vaults", + `GET /vaults/${VAULT_ID}/wrapped`, + "GET /vaults", + `GET /vaults/${VAULT_ID}/wrapped`, + ]); }); }); diff --git a/tests/unit/session-web-bot-auth-proxy-routes.test.ts b/tests/unit/session-web-bot-auth-proxy-routes.test.ts index fa5a85a..3799d16 100644 --- a/tests/unit/session-web-bot-auth-proxy-routes.test.ts +++ b/tests/unit/session-web-bot-auth-proxy-routes.test.ts @@ -1,10 +1,24 @@ import fs from "fs"; import os from "os"; import path from "path"; +import { Readable, Writable } from "stream"; import { afterEach, expect, expectTypeOf, test, vi } from "vitest"; import { Response } from "node-fetch"; const fetchMock = vi.fn(); +// Lets a test wrap the fs stream the SDK opens for a path upload. +const fsHooks = vi.hoisted(() => ({ + wrapReadStream: undefined as undefined | ((stream: NodeJS.ReadableStream) => void), +})); +vi.mock("fs", async () => { + const actual = await vi.importActual("fs"); + const createReadStream = ((...args: Parameters) => { + const stream = actual.createReadStream(...args); + fsHooks.wrapReadStream?.(stream); + return stream; + }) as typeof actual.createReadStream; + return { ...actual, default: { ...actual, createReadStream }, createReadStream }; +}); vi.mock("node-fetch", async () => { const actual = await vi.importActual("node-fetch"); return { ...actual, default: (...args: unknown[]) => fetchMock(...args) }; @@ -77,41 +91,103 @@ test("public types describe the options and the signing launch state", () => { }>(); }); -test("uploadFile rejects with HyperbrowserError for a non-existent file path and on stream errors without crashing", async () => { +// Consumes the body the way node-fetch 2 does: `body.pipe(req)` with no error +// listener of its own, and a rejection when the signal aborts. An unlistened +// FormData "error" therefore surfaces as an uncaught exception, which vitest +// reports as a failed run. +const pipeLikeNodeFetch = () => + fetchMock.mockImplementationOnce( + (_url: string, init: { body: NodeJS.ReadableStream; signal?: AbortSignal }) => + new Promise((resolve, reject) => { + const sink = new Writable({ write: (_chunk, _encoding, done) => done() }); + init.body.pipe(sink); + sink.on("finish", () => resolve(respond({ message: "uploaded" }))); + init.signal?.addEventListener("abort", () => + reject(Object.assign(new Error("The user aborted a request."), { name: "AbortError" })) + ); + }) + ); + +const failingStream = (message: string) => { + let sent = false; + return new Readable({ + read() { + if (sent) { + setImmediate(() => this.destroy(new Error(message))); + return; + } + sent = true; + this.push("partial"); + }, + }); +}; + +test("uploadFile rejects a missing or unreadable path before sending anything", async () => { const sdk = client(); const missingPath = path.join(os.tmpdir(), `hb-missing-${Date.now()}-${Math.random()}.txt`); + await expect(sdk.sessions.uploadFile("session-1", { fileInput: missingPath })).rejects.toThrow( + `File not found: ${missingPath}` + ); - await expect( - sdk.sessions.uploadFile("session-1", { fileInput: missingPath }) - ).rejects.toThrowError(HyperbrowserError); + const lockedFile = path.join(os.tmpdir(), `hb-locked-${Date.now()}-${Math.random()}.txt`); + fs.writeFileSync(lockedFile, "secret"); + fs.chmodSync(lockedFile, 0o000); + try { + // root can read anything, so only check the EACCES path when it applies. + if (process.getuid?.() !== 0) { + await expect(sdk.sessions.uploadFile("session-1", { fileInput: lockedFile })).rejects.toThrow( + `Permission denied accessing file: ${lockedFile}` + ); + } + } finally { + fs.rmSync(lockedFile, { force: true }); + } expect(fetchMock).not.toHaveBeenCalled(); +}); +test("uploadFile rejects, aborts the request, and does not crash when a file path stream fails", async () => { + const sdk = client(); const tempFile = path.join(os.tmpdir(), `hb-upload-${Date.now()}-${Math.random()}.txt`); fs.writeFileSync(tempFile, "hello"); + // Fail the real fs stream the SDK opens, after its checks pass. + fsHooks.wrapReadStream = (stream) => + stream.once("open", () => + setImmediate(() => (stream as fs.ReadStream).destroy(new Error("disk read failure"))) + ); + pipeLikeNodeFetch(); try { - fetchMock.mockImplementationOnce(async (_url: string, init: { body?: any }) => { - // Simulate a stream error after fs.stat/fs.access succeed while the request is in flight - const streams = (init?.body?._streams ?? []).filter( - (entry: unknown) => - entry && typeof entry === "object" && typeof (entry as any).emit === "function" - ); - if (streams[0]) { - streams[0].emit("error", new Error("disk read failure")); - } - await new Promise((resolve) => setTimeout(resolve, 50)); - return respond({ message: "uploaded" }); - }); - - await expect( - sdk.sessions.uploadFile("session-1", { fileInput: tempFile }) - ).rejects.toThrowError( - new HyperbrowserError(`Failed to read file at ${tempFile}: disk read failure`, undefined) + await expect(sdk.sessions.uploadFile("session-1", { fileInput: tempFile })).rejects.toThrow( + `Failed to read file at ${tempFile}: disk read failure` ); + expect(fetchMock.mock.lastCall![1].signal.aborted).toBe(true); } finally { + fsHooks.wrapReadStream = undefined; fs.rmSync(tempFile, { force: true }); } }); +test("uploadFile rejects, aborts the request, and does not crash when a caller's stream fails", async () => { + const sdk = client(); + const stream = failingStream("upstream reset"); + pipeLikeNodeFetch(); + await expect( + sdk.sessions.uploadFile("session-1", { fileInput: stream as any, fileName: "data.bin" }) + ).rejects.toThrow("Failed to read file stream data.bin: upstream reset"); + expect(fetchMock.mock.lastCall![1].signal.aborted).toBe(true); +}); + +test("uploadFile still uploads Buffers and healthy streams", async () => { + const sdk = client(); + pipeLikeNodeFetch(); + await expect( + sdk.sessions.uploadFile("session-1", { fileInput: Buffer.from("hi"), fileName: "a.txt" }) + ).resolves.toEqual({ message: "uploaded" }); + pipeLikeNodeFetch(); + await expect( + sdk.sessions.uploadFile("session-1", { fileInput: Readable.from(["x"]) as any, fileName: "b.txt" }) + ).resolves.toEqual({ message: "uploaded" }); +}); + test("WebsiteExtractTool.runnable parses a JSON string schema without mutating the caller's params", async () => { const sdk = client(); const startAndWaitSpy = vi From e122fdaf8ea8ee0898f39c93bbae40b359179350 Mon Sep 17 00:00:00 2001 From: Ninad Sinha Date: Tue, 10 Nov 2026 01:42:36 -0800 Subject: [PATCH 4/4] Bump version to 1.5.1 Co-Authored-By: Claude Opus 5.5 --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index 9b76fee..10a6587 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@hyperbrowser/sdk", - "version": "1.5.0", + "version": "1.5.1", "description": "Node SDK for Hyperbrowser API", "author": "", "repository": {