From ba68e9445d5970f154aae4d4dfff1cdf1fb86c99 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sun, 22 Nov 2026 12:25:44 +0100 Subject: [PATCH 1/6] perf(provision-kit): download app sources over Node HTTP --- packages/provision-kit/package.json | 4 +- .../src/install-source-deadline.test.ts | 1 + .../src/install-source-download.test.ts | 72 ++- .../src/install-source-download.ts | 90 ++- ...-source-network-transport-loopback.test.ts | 319 +++++++++++ ...source-network-transport-proxy.fixtures.ts | 413 ++++++++++++++ ...all-source-network-transport-proxy.test.ts | 215 ++++++++ ...l-source-network-transport-tls.fixtures.ts | 141 +++++ ...stall-source-network-transport.fixtures.ts | 516 ++++++++++++++++++ .../install-source-network-transport.test.ts | 38 ++ .../src/install-source-network-transport.ts | 231 ++++---- packages/provision-kit/tsconfig.json | 15 +- pnpm-lock.yaml | 6 +- website/docs/docs/commands.md | 1 + 14 files changed, 1928 insertions(+), 134 deletions(-) create mode 100644 packages/provision-kit/src/install-source-network-transport-loopback.test.ts create mode 100644 packages/provision-kit/src/install-source-network-transport-proxy.fixtures.ts create mode 100644 packages/provision-kit/src/install-source-network-transport-proxy.test.ts create mode 100644 packages/provision-kit/src/install-source-network-transport-tls.fixtures.ts create mode 100644 packages/provision-kit/src/install-source-network-transport.fixtures.ts diff --git a/packages/provision-kit/package.json b/packages/provision-kit/package.json index effccf51f1..6084b5daaa 100644 --- a/packages/provision-kit/package.json +++ b/packages/provision-kit/package.json @@ -44,7 +44,7 @@ } }, "devDependencies": { - "ipaddr.js": "^2.5.0", - "undici": "7.30.1" + "@agent-device/test-kit": "workspace:*", + "ipaddr.js": "^2.5.0" } } diff --git a/packages/provision-kit/src/install-source-deadline.test.ts b/packages/provision-kit/src/install-source-deadline.test.ts index 6c805da3a6..1f203d1394 100644 --- a/packages/provision-kit/src/install-source-deadline.test.ts +++ b/packages/provision-kit/src/install-source-deadline.test.ts @@ -194,6 +194,7 @@ test('a DNS approval stall reports the connect phase timeout', async () => { assert.deepEqual(error.details, { reason: 'transfer_phase_timeout', transferPhase: 'connect', + networkErrorCode: 'connect-timeout', timeoutMs: 30_000, }); assert.ok(isRequestCanceledError(error.cause)); diff --git a/packages/provision-kit/src/install-source-download.test.ts b/packages/provision-kit/src/install-source-download.test.ts index 503ca1ea99..078a3138a0 100644 --- a/packages/provision-kit/src/install-source-download.test.ts +++ b/packages/provision-kit/src/install-source-download.test.ts @@ -1,12 +1,14 @@ import assert from 'node:assert/strict'; import dns from 'node:dns/promises'; import fs from 'node:fs/promises'; +import path from 'node:path'; import { PassThrough, Readable } from 'node:stream'; import { afterEach, beforeEach, test, vi } from 'vitest'; import { AppError, isRequestCanceledError } from '@agent-device/kernel/errors'; import { TRANSFER_BODY_INACTIVITY_TIMEOUT_MS, TRANSFER_CONNECT_TIMEOUT_MS, + TRANSFER_RESPONSE_HEADER_TIMEOUT_MS, isTransferPhaseTimeoutError, } from '@agent-device/host-kit/transport'; import { mkdtempForTest } from './tmp-dir.fixtures.ts'; @@ -171,6 +173,51 @@ test('download identifies the daemon as the requester and preserves the network } }); +test.for(['ECONNRESET', 'ECONNREFUSED', 'ENOTFOUND', 'ETIMEDOUT', 'ERR_TLS_CERT_ALTNAME_INVALID'])( + 'download preserves %s while waiting for headers and streaming a partial file', + async (code) => { + const tempRoot = await mkdtempForTest('agent-device-download-partial-'); + const restoreLookup = mockApprovedLookup(); + const transportError = Object.assign(new Error('private transport diagnostic'), { code }); + const body = new PassThrough(); + const requester = vi + .spyOn(networkTransport, 'requestApprovedUrl') + .mockRejectedValueOnce(transportError) + .mockResolvedValueOnce(response(200, body)); + const download = () => + downloadInstallSource({ + tempDir: tempRoot, + url: 'https://example.com/app.apk', + signal: new AbortController().signal, + environment: {}, + }); + const assertCode = (error: unknown) => { + assert.ok(error instanceof AppError); + assert.equal(error.code, 'COMMAND_FAILED'); + assert.deepEqual(error.details, { networkErrorCode: code }); + assert.equal(error.cause, transportError); + assert.ok(!error.message.includes(transportError.message)); + return true; + }; + try { + await assert.rejects(download(), assertCode); + const outcome = assert.rejects(download(), assertCode); + body.write('partial data'); + await vi.waitFor(async () => { + assert.equal(await fs.readFile(path.join(tempRoot, 'app.apk'), 'utf8'), 'partial data'); + }); + body.destroy(transportError); + await outcome; + assert.deepEqual(await fs.readdir(tempRoot), []); + } finally { + body.destroy(); + requester.mockRestore(); + restoreLookup(); + await fs.rm(tempRoot, { recursive: true, force: true }); + } + }, +); + test('download omits network error codes that are not identifiers', async () => { const tempRoot = await mkdtempForTest('agent-device-download-network-error-code-'); const lookup = vi @@ -286,23 +333,37 @@ function mockApprovedLookup(): () => void { return () => lookup.mockRestore(); } -function assertPhaseTimeout(error: unknown, phase: string, timeoutMs: number): void { +function assertPhaseTimeout( + error: unknown, + phase: string, + timeoutMs: number, + networkErrorCode: string, +): void { assert.ok(error instanceof AppError, 'phase expiry must stay a typed AppError'); assert.ok(isTransferPhaseTimeoutError(error), 'phase expiry must keep its typed reason'); assert.equal(isRequestCanceledError(error), false, 'a phase timeout is not caller cancellation'); assert.deepEqual(error.details, { reason: 'transfer_phase_timeout', transferPhase: phase, + networkErrorCode, timeoutMs, }); } -test('a connect that never completes expires at the adopted connect ceiling with typed evidence', async () => { +test.for([ + { phase: 'connect', timeout: TRANSFER_CONNECT_TIMEOUT_MS, code: 'connect-timeout' }, + { + phase: 'response-headers', + timeout: TRANSFER_RESPONSE_HEADER_TIMEOUT_MS, + code: 'header-timeout', + }, +])('a stalled $phase reports $code', async ({ phase, timeout, code }) => { const tempRoot = await mkdtempForTest('agent-device-download-connect-stall-'); const restoreLookup = mockApprovedLookup(); const requestMock = vi.spyOn(networkTransport, 'requestApprovedUrl').mockImplementation( (args) => new Promise((_resolve, reject) => { + if (phase === 'response-headers') args.onConnected?.(); args.signal.addEventListener('abort', () => reject(args.signal.reason), { once: true, }); @@ -316,9 +377,9 @@ test('a connect that never completes expires at the adopted connect ceiling with environment: process.env, }).catch((error: unknown) => error); await flushRealIOMacrotasks(); - await vi.advanceTimersByTimeAsync(TRANSFER_CONNECT_TIMEOUT_MS + 1); + await vi.advanceTimersByTimeAsync(timeout + 1); const error = await outcome; - assertPhaseTimeout(error, 'connect', TRANSFER_CONNECT_TIMEOUT_MS); + assertPhaseTimeout(error, phase, timeout, code); } finally { requestMock.mockRestore(); restoreLookup(); @@ -342,7 +403,8 @@ test('a stalled response body expires at the inactivity ceiling even without cal await flushRealIOMacrotasks(); await vi.advanceTimersByTimeAsync(TRANSFER_BODY_INACTIVITY_TIMEOUT_MS + 1); const error = await outcome; - assertPhaseTimeout(error, 'response-body', TRANSFER_BODY_INACTIVITY_TIMEOUT_MS); + assertPhaseTimeout(error, 'response-body', TRANSFER_BODY_INACTIVITY_TIMEOUT_MS, 'body-timeout'); + assert.deepEqual(await fs.readdir(tempRoot), []); } finally { requestMock.mockRestore(); restoreLookup(); diff --git a/packages/provision-kit/src/install-source-download.ts b/packages/provision-kit/src/install-source-download.ts index ae4ecbc95f..cf98a941a8 100644 --- a/packages/provision-kit/src/install-source-download.ts +++ b/packages/provision-kit/src/install-source-download.ts @@ -116,24 +116,52 @@ async function requestHop( onConnected: () => watchdog.arm('response-headers', phases.responseHeaderTimeoutMs), }); } catch (error) { - if (phases.isPhaseTimeout(error)) throw error; - const reason: unknown = watchdog.signal.reason; - if (reason instanceof AppError && phases.isPhaseTimeout(reason)) { - throw new AppError(reason.code, reason.message, reason.details, error); - } - if (error instanceof AppError) throw error; - const networkErrorCode = readNetworkErrorCode(error); - throw new AppError( - 'COMMAND_FAILED', - networkErrorCode - ? `The daemon failed to fetch the app source (network error code: ${networkErrorCode})` - : 'The daemon failed to fetch the app source', - networkErrorCode ? { networkErrorCode } : undefined, - error, - ); + const timeout = phaseTimeout(error, phases); + if (timeout) throw timeout; + if (isSignalFailure(error, watchdog.signal)) throw watchdog.signal.reason; + if (error instanceof AppError && !readNetworkErrorCode(error.cause)) throw error; + throw downloadNetworkError(error instanceof AppError ? error.cause : error); } } +function phaseTimeout(error: unknown, phases: TransferPhaseTools): AppError | undefined { + const reason: unknown = phases.watchdog.signal.reason; + const timeout = phases.isPhaseTimeout(error) ? error : reason; + if (!(timeout instanceof AppError) || !phases.isPhaseTimeout(timeout)) return undefined; + const transferPhase = timeout.details?.transferPhase; + const networkErrorCode = + transferPhase === 'connect' + ? 'connect-timeout' + : transferPhase === 'response-headers' + ? 'header-timeout' + : 'body-timeout'; + return new AppError( + timeout.code, + timeout.message, + { ...timeout.details, networkErrorCode }, + error === timeout ? timeout.cause : error, + ); +} + +function isSignalFailure(error: unknown, signal: AbortSignal): boolean { + return ( + signal.aborted && + (error === signal.reason || (error instanceof Error && error.cause === signal.reason)) + ); +} + +function downloadNetworkError(error: unknown): AppError { + const networkErrorCode = readNetworkErrorCode(error); + return new AppError( + 'COMMAND_FAILED', + networkErrorCode + ? `The daemon failed to fetch the app source (network error code: ${networkErrorCode})` + : 'The daemon failed to fetch the app source', + networkErrorCode ? { networkErrorCode } : undefined, + error, + ); +} + // Only the code crosses to the caller: a remote daemon's cause message can name // its resolved addresses, proxy, or server-supplied certificate names. function readNetworkErrorCode(error: unknown): string | undefined { @@ -198,22 +226,28 @@ async function writeResponse( callback(null, chunk); }, }); + let created = false; + let failureSource: 'body' | 'file' | undefined; + response.body.once('error', () => { + failureSource ??= 'body'; + }); + const destination = createWriteStream(destinationPath, { flags: 'wx' }); + destination.once('open', () => { + created = true; + }); + destination.once('error', () => { + failureSource ??= 'file'; + }); try { - await pipeline( - response.body, - progress, - byteLimit, - createWriteStream(destinationPath, { - flags: 'wx', - }), - { signal: watchdog.signal }, - ); + await pipeline(response.body, progress, byteLimit, destination, { signal: watchdog.signal }); return destinationPath; } catch (error) { - await fs.rm(destinationPath, { force: true }).catch(() => {}); - if (phases.isPhaseTimeout(error)) throw error; - if (phases.isPhaseTimeout(watchdog.signal.reason)) throw watchdog.signal.reason; - throw error; + if (created) await fs.rm(destinationPath, { force: true }).catch(() => {}); + const timeout = phaseTimeout(error, phases); + if (timeout) throw timeout; + if (isSignalFailure(error, watchdog.signal)) throw watchdog.signal.reason; + if (error instanceof AppError || failureSource === 'file') throw error; + throw downloadNetworkError(error); } } diff --git a/packages/provision-kit/src/install-source-network-transport-loopback.test.ts b/packages/provision-kit/src/install-source-network-transport-loopback.test.ts new file mode 100644 index 0000000000..b238f5d851 --- /dev/null +++ b/packages/provision-kit/src/install-source-network-transport-loopback.test.ts @@ -0,0 +1,319 @@ +import assert from 'node:assert/strict'; +import path from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { afterAll, beforeAll, test } from 'vitest'; + +import { skipWhenLoopbackUnavailable } from '@agent-device/test-kit'; + +import * as nodeTransport from './install-source-network-transport.ts'; +import { + runTlsScenarios, + transportModulePath, + type TlsScenario, +} from './install-source-network-transport-tls.fixtures.ts'; +import { + ARTIFACT_BODY, + APPROVED_HOSTNAME, + TRANSPORT_TEST_TIMEOUT_MS, + approvedUrl, + directEnvironment, + noProxyEnvironment, + observeRequest, + operatorAbortAfter, + proxiedEnvironment, + startLoopbackLab, + type LoopbackLab, +} from './install-source-network-transport.fixtures.ts'; + +const HERE = path.dirname(fileURLToPath(import.meta.url)); +const REPO_ROOT = path.resolve(HERE, '../../..'); + +/** Loopback certificate trusted by the TLS child process; its subject names cover `localhost`. */ +const FIXTURE_CERTIFICATE = path.join( + REPO_ROOT, + 'test/integration/provider-scenarios/fixtures/localhost-cert.pem', +); + +let lab: LoopbackLab; + +beforeAll(async () => { + // The lab binds 127.0.0.1, so it follows the shared loopback policy: an environment that only + // optionally restricts loopback binds leaves the lab unstarted and each test skips itself, while + // one that requires loopback coverage fails here. There is no test context in a hook, so the + // skip arm is a no-op; the per-test guard reports the skip. + if ( + await skipWhenLoopbackUnavailable({ skip: () => {} }, 'install-source transport loopback lab') + ) { + return; + } + lab = await startLoopbackLab(REPO_ROOT); +}); + +afterAll(async () => { + await lab?.close(); +}); + +function run(params: { + url: URL; + headers?: Record; + signal: AbortSignal; + environment: NodeJS.ProcessEnv; + readBody?: 'none'; + caseDeadlineMs?: number; +}) { + return observeRequest(nodeTransport, { lab, ...params }); +} + +test(`a direct request keeps the URL identity and dials the approved address`, async (t) => { + if (await skipWhenLoopbackUnavailable(t)) return; + const observed = await run({ + url: new URL(`http://${APPROVED_HOSTNAME}:${lab.originPort}/app.zip?token=abc`), + headers: { 'x-custom': 'yes' }, + signal: AbortSignal.timeout(TRANSPORT_TEST_TIMEOUT_MS), + environment: directEnvironment(), + }); + + assert.equal(observed.outcome, 'response'); + assert.equal(observed.statusCode, 200); + assert.equal(observed.body, ARTIFACT_BODY); + assert.deepEqual(observed.headers ?? {}, { + 'content-type': ['application/octet-stream'], + 'x-repeated': ['a', 'b'], + 'set-cookie': ['c=1', 'd=2'], + 'x-origin-host': [`approved.invalid:`], + }); + assert.deepEqual(observed.originSaw, [ + { + method: 'GET', + url: '/app.zip?token=abc', + host: 'approved.invalid:', + custom: 'yes', + }, + ]); + assert.deepEqual(observed.connectAuthorities, []); +}); + +test(`a 302 is returned un-followed so the download contract owns redirects`, async (t) => { + if (await skipWhenLoopbackUnavailable(t)) return; + const observed = await run({ + url: approvedUrl(lab.originPort, '/redirect'), + signal: AbortSignal.timeout(TRANSPORT_TEST_TIMEOUT_MS), + environment: directEnvironment(), + }); + + assert.equal(observed.statusCode, 302); + assert.deepEqual(observed.headers?.['location'], ['http://cdn.invalid/final']); + assert.equal(observed.originSaw?.length, 1); +}); + +test(`a proxied request tunnels to the approved address and keeps the Host name`, async (t) => { + if (await skipWhenLoopbackUnavailable(t)) return; + const observed = await run({ + url: new URL(`http://${APPROVED_HOSTNAME}:${lab.originPort}/app.zip`), + headers: { 'x-custom': 'yes' }, + signal: AbortSignal.timeout(TRANSPORT_TEST_TIMEOUT_MS), + environment: proxiedEnvironment(lab.proxyPort), + }); + + assert.equal(observed.statusCode, 200); + assert.equal(observed.body, ARTIFACT_BODY); + assert.deepEqual(observed.connectAuthorities, ['127.0.0.1:']); + assert.deepEqual(observed.originSaw?.[0]?.host, 'approved.invalid:'); + assert.equal(observed.liveProxySockets, 0); +}); + +test(`NO_PROXY scoped to the URL host bypasses the proxy`, async (t) => { + if (await skipWhenLoopbackUnavailable(t)) return; + const observed = await run({ + url: new URL(`http://${APPROVED_HOSTNAME}:${lab.originPort}/app.zip`), + signal: AbortSignal.timeout(TRANSPORT_TEST_TIMEOUT_MS), + environment: noProxyEnvironment(lab.proxyPort, APPROVED_HOSTNAME), + }); + + assert.equal(observed.statusCode, 200); + assert.deepEqual(observed.connectAuthorities, []); +}); + +test(`a proxy that refuses CONNECT fails the request with the tunnel status`, async (t) => { + if (await skipWhenLoopbackUnavailable(t)) return; + const observed = await run({ + url: approvedUrl(lab.refusalPort), + signal: AbortSignal.timeout(TRANSPORT_TEST_TIMEOUT_MS), + environment: proxiedEnvironment(lab.proxyPort), + }); + + assert.equal(observed.outcome, 'rejection'); + // The error identifies the CONNECT refusal status. + assert.match(observed.error?.message ?? '', /Proxy response \(502\) !== 200 when HTTP Tunneling/); + assert.equal(observed.liveProxySockets, 0); + assert.equal(observed.error?.code, 'EPROXYTUNNEL'); +}); + +test(`a refused TCP connection is reported as ECONNREFUSED`, async (t) => { + if (await skipWhenLoopbackUnavailable(t)) return; + const observed = await run({ + url: new URL('http://approved.invalid:1/app.zip'), + signal: AbortSignal.timeout(TRANSPORT_TEST_TIMEOUT_MS), + environment: directEnvironment(), + }); + + assert.equal(observed.outcome, 'rejection'); + assert.equal(observed.error?.code, 'ECONNREFUSED'); + assert.equal(observed.error?.message, 'connect ECONNREFUSED 127.0.0.1:1'); +}); + +test(`an operator abort before the response rejects with the caller's own error`, async (t) => { + if (await skipWhenLoopbackUnavailable(t)) return; + const observed = await run({ + url: approvedUrl(lab.silentPort), + signal: operatorAbortAfter(150), + environment: directEnvironment(), + }); + + assert.equal(observed.outcome, 'rejection'); + assert.equal(observed.error?.message, 'operator stop'); +}); + +test(`an operator abort before the response rejects through a proxy tunnel`, async (t) => { + if (await skipWhenLoopbackUnavailable(t)) return; + const observed = await run({ + url: approvedUrl(lab.silentPort), + signal: operatorAbortAfter(150), + environment: proxiedEnvironment(lab.proxyPort), + }); + + assert.equal(observed.outcome, 'rejection'); + assert.equal(observed.error?.message, 'operator stop'); + assert.equal(observed.liveProxySockets, 0); +}); + +test(`a signal timeout before the response rejects as a timeout`, async (t) => { + if (await skipWhenLoopbackUnavailable(t)) return; + const observed = await run({ + url: approvedUrl(lab.silentPort), + signal: AbortSignal.timeout(150), + environment: directEnvironment(), + }); + + assert.equal(observed.outcome, 'rejection'); + assert.equal(observed.error?.name, 'TimeoutError'); + assert.equal(observed.error?.message, 'The operation was aborted due to timeout'); +}); + +test(`an operator abort mid-body delivers the bytes read and ends the stream with the caller's error`, async (t) => { + if (await skipWhenLoopbackUnavailable(t)) return; + const observed = await run({ + url: approvedUrl(lab.stallerPort), + signal: operatorAbortAfter(200), + environment: directEnvironment(), + }); + + assert.equal(observed.statusCode, 200); + assert.equal(observed.outcome, 'stream-interrupted'); + assert.equal(observed.body, 'partial-chunk'); + assert.equal(observed.error?.message, 'operator stop'); +}); + +test(`an operator abort mid-body through a proxy ends the stream with the caller's error`, async (t) => { + if (await skipWhenLoopbackUnavailable(t)) return; + const observed = await run({ + url: approvedUrl(lab.stallerPort), + signal: operatorAbortAfter(200), + environment: proxiedEnvironment(lab.proxyPort), + }); + + assert.equal(observed.statusCode, 200); + assert.equal(observed.outcome, 'stream-interrupted'); + assert.equal(observed.body, 'partial-chunk'); + assert.equal(observed.error?.message, 'operator stop'); + assert.equal(observed.liveProxySockets, 0); +}); + +test(`close releases the body and the connection, and a second call is reported`, async (t) => { + if (await skipWhenLoopbackUnavailable(t)) return; + const observed = await run({ + url: new URL(`http://${APPROVED_HOSTNAME}:${lab.originPort}/app.zip`), + signal: AbortSignal.timeout(TRANSPORT_TEST_TIMEOUT_MS), + environment: proxiedEnvironment(lab.proxyPort), + readBody: 'none', + }); + + assert.equal(observed.statusCode, 200); + assert.deepEqual(observed.closeResults?.[0], 'ok'); + assert.equal(observed.liveProxySockets, 0); + assert.deepEqual(observed.closeResults?.[1], 'ok'); +}); + +test(`a proxy that never answers CONNECT is closed on caller cancellation`, async (t) => { + if (await skipWhenLoopbackUnavailable(t)) return; + const observed = await run({ + url: approvedUrl(lab.stalledConnectPort), + signal: operatorAbortAfter(150), + environment: proxiedEnvironment(lab.proxyPort), + }); + + assert.equal(observed.outcome, 'rejection'); + assert.equal(observed.error?.message, 'operator stop'); + assert.deepEqual(observed.connectAuthorities, ['127.0.0.1:']); + assert.equal(observed.liveProxySockets, 0); +}); + +test('The downloader derives TLS trust, SNI, and the certificate identity check from the URL host', async (t) => { + if (await skipWhenLoopbackUnavailable(t)) return; + // TLS trust is fixed when a process starts, so the test runs the TLS scenarios in a child + // process spawned with the loopback fixture certificate as an extra CA. The child owns no + // listeners: the parent's TLS origin echoes the SNI name it saw, and that is how the dial is + // verified. + const scenarios: TlsScenario[] = [ + 'direct', + 'proxied', + 'proxied-literal-ip', + 'direct-altname-mismatch', + 'direct-literal-ip', + ]; + const results = await runTlsScenarios({ + subjectPath: transportModulePath(HERE), + tlsOriginPort: lab.tlsOriginPort, + proxyPort: lab.proxyPort, + scenarios, + trustFixtureCertificate: true, + fixtureCertificatePath: FIXTURE_CERTIFICATE, + }); + const byScenario = new Map(results.map((result) => [result.scenario, result])); + + // SNI names the URL host, so the server answers with that name. A literal IP cannot be an SNI + // name, and the client omits it there; the fixture certificate covers `127.0.0.1` as an IP + // subject alternative name, so those connections still complete. + const expectedSni: [TlsScenario, string][] = [ + ['direct', 'localhost'], + ['proxied', 'localhost'], + ['proxied-literal-ip', 'false'], + ['direct-literal-ip', 'false'], + ]; + for (const [scenario, sniHeader] of expectedSni) { + assert.deepEqual( + { scenario, ...byScenario.get(scenario) }, + { scenario, outcome: 'response', statusCode: 200, body: 'body', sniHeader }, + 'a trusted loopback certificate must complete the request with the URL host as SNI', + ); + } + assert.equal( + byScenario.get('direct-altname-mismatch')?.error?.code, + 'ERR_TLS_CERT_ALTNAME_INVALID', + 'the certificate identity check must stay on the URL host', + ); +}); + +test('The downloader rejects the loopback fixture certificate when it is not trusted', async (t) => { + if (await skipWhenLoopbackUnavailable(t)) return; + const [result] = await runTlsScenarios({ + subjectPath: transportModulePath(HERE), + tlsOriginPort: lab.tlsOriginPort, + proxyPort: lab.proxyPort, + scenarios: ['direct'], + trustFixtureCertificate: false, + fixtureCertificatePath: FIXTURE_CERTIFICATE, + }); + assert.equal(result?.outcome, 'rejection'); + assert.equal(result?.error?.code, 'DEPTH_ZERO_SELF_SIGNED_CERT'); +}); diff --git a/packages/provision-kit/src/install-source-network-transport-proxy.fixtures.ts b/packages/provision-kit/src/install-source-network-transport-proxy.fixtures.ts new file mode 100644 index 0000000000..aa06baa2f7 --- /dev/null +++ b/packages/provision-kit/src/install-source-network-transport-proxy.fixtures.ts @@ -0,0 +1,413 @@ +import http from 'node:http'; +import https from 'node:https'; +import type { Duplex } from 'node:stream'; + +import { runTransportChild } from './install-source-network-transport-tls.fixtures.ts'; +import { + APPROVED_ADDRESS, + APPROVED_HOSTNAME, + ARTIFACT_BODY, + authoritiesWithoutPorts, + createTlsArtifactOrigin, + errorShape, + forwardConnect, + listen, + readTlsFixturePair, + requestsWithoutPorts, + trackSockets, + type ErrorShape, + type ObservedRequest, + type TransportSubject, +} from './install-source-network-transport.fixtures.ts'; + +/** + * Loopback-only lab for the proxy-scheme and proxy-authentication contract of the install-source + * transport (#4674 evidence). Every listener binds 127.0.0.1, so no case leaves the machine, and + * the origin hostname is a reserved bad name, so a request that reaches an origin proves the + * transport dialed the approved address it was handed. + * + * Both lab proxies speak CONNECT and demand one synthetic fixture-only Basic credential; a real + * credential is never used, read from the environment, or logged. The `https` proxy wraps the same + * CONNECT exchange in TLS with the loopback fixture certificate, which the client side trusts only + * when a spawned child is given that certificate as an extra CA. + */ + +/** Synthetic fixture-only proxy credential. Not a real credential; only this lab accepts it. */ +const PROXY_FIXTURE_USER = 'fixture-only-user'; +/** Synthetic fixture-only proxy credential. Not a real credential; only this lab accepts it. */ +const PROXY_FIXTURE_PASSWORD = 'fixture-only-secret'; + +/** The exact `Proxy-Authorization` value the lab proxies demand on CONNECT. */ +export const EXPECTED_PROXY_AUTHORIZATION = `Basic ${Buffer.from( + `${PROXY_FIXTURE_USER}:${PROXY_FIXTURE_PASSWORD}`, + 'utf8', +).toString('base64')}`; + +/** The proxy URL handed to the transport through the proxy environment variables. */ +export function authProxyUrl(scheme: 'http' | 'https', port: number): string { + return `${scheme}://${PROXY_FIXTURE_USER}:${PROXY_FIXTURE_PASSWORD}@${APPROVED_ADDRESS}:${port}`; +} + +/** Environment selecting the authenticating loopback HTTP proxy for both URL schemes. */ +export function authHttpProxyEnvironment(proxyPort: number): NodeJS.ProcessEnv { + const proxy = authProxyUrl('http', proxyPort); + return { http_proxy: proxy, https_proxy: proxy }; +} + +type ProxyAuthLabMark = { + requests: number; + connect: number; + proxySni: number; + plainProxySockets: number; + tlsProxySockets: number; +}; + +export type ProxyAuthLab = { + originPort: number; + tlsOriginPort: number; + /** Plain-HTTP CONNECT proxy demanding the fixture credential. */ + proxyPort: number; + /** TLS CONNECT proxy demanding the fixture credential, for the `https` proxy scheme. */ + tlsProxyPort: number; + mark(): ProxyAuthLabMark; + requestsSince(mark: ProxyAuthLabMark): ObservedRequest[]; + connectAuthoritiesSince(mark: ProxyAuthLabMark): string[]; + proxyAuthorizationsSince(mark: ProxyAuthLabMark): (string | undefined)[]; + /** The SNI names the TLS proxy accepted at its handshakes, after `mark`. */ + proxySniSince(mark: ProxyAuthLabMark): (string | undefined)[]; + liveProxySocketsSince(mark: ProxyAuthLabMark): number; + settleSince(mark: ProxyAuthLabMark): Promise; + dropProxySockets(): void; + close(): Promise; +}; + +const SETTLE_DEADLINE_MS = 700; +const SETTLE_POLL_MS = 20; + +/** One CONNECT exchange: demand the fixture credential, then tunnel to the approved address. */ +function handleConnect( + record: { authorities: string[]; authorizations: (string | undefined)[] }, + request: http.IncomingMessage, + clientSocket: Duplex, + head: Buffer, +): void { + const authority = request.url ?? ''; + record.authorities.push(authority); + record.authorizations.push(request.headers['proxy-authorization']); + if (request.headers['proxy-authorization'] !== EXPECTED_PROXY_AUTHORIZATION) { + clientSocket.write('HTTP/1.1 407 Proxy Authentication Required\r\ncontent-length: 0\r\n\r\n'); + clientSocket.end(); + return; + } + const port = Number(authority.split(':').at(-1)); + forwardConnect(port, clientSocket, head); +} + +export async function startProxyAuthLab(root: string): Promise { + const { key, cert } = readTlsFixturePair(root); + const requests: ObservedRequest[] = []; + const proxySni: (string | undefined)[] = []; + const record = { authorities: [] as string[], authorizations: [] as (string | undefined)[] }; + + const origin = http.createServer((request, response) => { + requests.push({ + method: request.method ?? '', + url: request.url ?? '', + host: request.headers.host, + }); + response.writeHead(200, { 'content-type': 'application/octet-stream' }); + response.end(ARTIFACT_BODY); + }); + const originPort = await listen(origin); + + const tlsOrigin = createTlsArtifactOrigin({ key, cert }); + const tlsOriginPort = await listen(tlsOrigin); + + const proxy = http.createServer((_request, response) => { + response.writeHead(501).end(); + }); + proxy.on('connect', (request, clientSocket, head) => + handleConnect(record, request, clientSocket, head), + ); + const proxySockets = trackSockets(proxy); + const proxyPort = await listen(proxy); + + // The same CONNECT proxy behind TLS: an `https://` proxy URL must reach this listener. + const tlsProxyServer = https.createServer({ key, cert }, (_request, response) => { + response.writeHead(501).end(); + }); + tlsProxyServer.on('connect', (request, clientSocket, head) => + handleConnect(record, request, clientSocket, head), + ); + tlsProxyServer.on('tlsClientError', () => {}); + // Records the name each client asked for at the handshake, so a case can prove the proxy dial + // presented the proxy host as SNI. A handshake without SNI records `undefined`. + tlsProxyServer.on('secureConnection', (socket) => + proxySni.push(typeof socket.servername === 'string' ? socket.servername : undefined), + ); + const tlsProxySockets = trackSockets(tlsProxyServer); + const tlsProxyPort = await listen(tlsProxyServer); + + return { + originPort, + tlsOriginPort, + proxyPort, + tlsProxyPort, + mark: () => ({ + requests: requests.length, + connect: record.authorities.length, + proxySni: proxySni.length, + plainProxySockets: proxySockets.highestId(), + tlsProxySockets: tlsProxySockets.highestId(), + }), + requestsSince: (mark) => requestsWithoutPorts(requests.slice(mark.requests)), + connectAuthoritiesSince: (mark) => + authoritiesWithoutPorts(record.authorities.slice(mark.connect)), + proxyAuthorizationsSince: (mark) => record.authorizations.slice(mark.connect), + proxySniSince: (mark) => proxySni.slice(mark.proxySni), + liveProxySocketsSince: (mark) => + proxySockets.liveSince(mark.plainProxySockets) + + tlsProxySockets.liveSince(mark.tlsProxySockets), + settleSince: async (mark) => { + const deadline = Date.now() + SETTLE_DEADLINE_MS; + while ( + Date.now() < deadline && + (proxySockets.liveSince(mark.plainProxySockets) > 0 || + tlsProxySockets.liveSince(mark.tlsProxySockets) > 0) + ) { + await new Promise((resolve) => setTimeout(resolve, SETTLE_POLL_MS)); + } + }, + dropProxySockets: () => { + proxySockets.destroyAll(); + tlsProxySockets.destroyAll(); + }, + close: async () => { + for (const server of [origin, tlsOrigin, proxy, tlsProxyServer]) { + (server as http.Server).closeAllConnections?.(); + server.close(); + } + proxySockets.destroyAll(); + tlsProxySockets.destroyAll(); + }, + }; +} + +type ProxyAuthObservation = { + outcome: 'response' | 'rejection' | 'hung'; + statusCode?: number; + body?: string; + error?: ErrorShape; + originSaw?: ObservedRequest[]; + connectAuthorities?: string[]; + proxyAuthorizations?: (string | undefined)[]; + liveProxySockets?: number; +}; + +/** Runs one in-process request through the subject and reports what happened instead of throwing. */ +export async function observeProxyRequest( + subject: TransportSubject, + params: { + url: URL; + signal: AbortSignal; + environment: NodeJS.ProcessEnv; + lab: ProxyAuthLab; + caseDeadlineMs: number; + }, +): Promise { + const mark = params.lab.mark(); + const deadline = params.caseDeadlineMs; + const work = (async () => { + const response = await subject.requestApprovedUrl({ + url: params.url, + approvedAddress: APPROVED_ADDRESS, + family: 4, + headers: {}, + signal: params.signal, + environment: params.environment, + }); + let body = ''; + for await (const chunk of response.body as AsyncIterable) { + body += Buffer.from(chunk).toString('utf8'); + } + await response.close(); + return { response, body }; + })(); + const result = await Promise.race([ + work.then( + (value) => ({ kind: 'ok' as const, value }), + (error: unknown) => ({ kind: 'failed' as const, error }), + ), + new Promise<{ kind: 'hung' }>((resolve) => { + const timer = setTimeout(() => resolve({ kind: 'hung' }), deadline); + timer.unref?.(); + }), + ]); + await params.lab.settleSince(mark); + const base = { + originSaw: params.lab.requestsSince(mark), + connectAuthorities: params.lab.connectAuthoritiesSince(mark), + proxyAuthorizations: params.lab.proxyAuthorizationsSince(mark), + liveProxySockets: params.lab.liveProxySocketsSince(mark), + }; + if (result.kind === 'hung') { + params.lab.dropProxySockets(); + await params.lab.settleSince(mark); + return { outcome: 'hung', ...base }; + } + if (result.kind === 'failed') { + return { outcome: 'rejection', ...base, error: errorShape(result.error) }; + } + return { + outcome: 'response', + ...base, + statusCode: result.value.response.statusCode, + body: result.value.body, + }; +} + +export type ProxyAuthScenario = + | 'auth-http-proxy-http-origin' + | 'auth-http-proxy-tls-origin' + | 'auth-https-proxy-http-origin' + | 'auth-named-https-proxy-tls-origin'; + +type ProxyAuthScenarioResult = { + scenario: ProxyAuthScenario; + outcome: 'response' | 'rejection'; + statusCode?: number; + body?: string; + sniHeader?: string; + error?: ErrorShape; + /** + * Child TCP resources remaining above the initial process count. Use one scenario per child + * to attribute the count to an individual request. + */ + openSockets: number; +}; + +/** + * Runs proxy-scheme scenarios in a fresh process. Any scenario that crosses TLS — the TLS origin + * or the `https` proxy — needs the loopback fixture certificate trusted, and TLS trust is fixed + * while a process starts, so the caller passes `NODE_EXTRA_CA_CERTS` at spawn time. The child owns + * no listeners; the parent's lab records the CONNECT authorities and proxy credentials. + */ +export async function runProxyAuthScenarios(params: { + /** Absolute path of the transport module the child imports. */ + subjectPath: string; + originPort: number; + tlsOriginPort: number; + proxyPort: number; + tlsProxyPort: number; + scenarios: ProxyAuthScenario[]; + /** Trusts the loopback fixture certificate when true. */ + trustFixtureCertificate: boolean; + fixtureCertificatePath: string; +}): Promise { + return await runTransportChild( + proxyChildSource(), + [ + params.subjectPath, + String(params.originPort), + String(params.tlsOriginPort), + String(params.proxyPort), + String(params.tlsProxyPort), + ...params.scenarios, + ], + params.trustFixtureCertificate ? params.fixtureCertificatePath : '', + params.scenarios.length * 6_000, + ); +} + +/** + * The child's source. Plain ESM so the child needs no loader beyond type stripping: it imports the + * transport module by absolute path. Arguments: transport module, the four lab ports, then the + * scenarios to run. + */ +function proxyChildSource(): string { + return ` +import { pathToFileURL } from 'node:url'; + +const [subjectPath, originPort, tlsOriginPort, proxyPort, tlsProxyPort, ...scenarios] = + process.argv.slice(2); +const { requestApprovedUrl } = await import(pathToFileURL(subjectPath).href); +const APPROVED_ADDRESS = '127.0.0.1'; +const USER = ${JSON.stringify(PROXY_FIXTURE_USER)}; +const PASSWORD = ${JSON.stringify(PROXY_FIXTURE_PASSWORD)}; +const authProxy = (scheme, port) => + scheme + '://' + USER + ':' + PASSWORD + '@' + APPROVED_ADDRESS + ':' + port; + +const shape = (error) => ({ + name: error?.name, + code: error?.code, + message: error?.message, +}); + +const scenarioSpec = { + 'auth-http-proxy-http-origin': { + url: 'http://${APPROVED_HOSTNAME}:' + originPort + '/app.zip', + environment: { http_proxy: authProxy('http', proxyPort), https_proxy: authProxy('http', proxyPort) }, + }, + 'auth-http-proxy-tls-origin': { + url: 'https://localhost:' + tlsOriginPort + '/artifact.bin', + environment: { https_proxy: authProxy('http', proxyPort) }, + }, + 'auth-https-proxy-http-origin': { + url: 'http://${APPROVED_HOSTNAME}:' + originPort + '/app.zip', + environment: { http_proxy: authProxy('https', tlsProxyPort), https_proxy: authProxy('https', tlsProxyPort) }, + }, + // The proxy URL names its host instead of spelling the loopback address, so the proxy handshake + // carries that name as SNI, and the origin is TLS, so it echoes the origin SNI back. + 'auth-named-https-proxy-tls-origin': { + url: 'https://localhost:' + tlsOriginPort + '/artifact.bin', + environment: { https_proxy: 'https://' + USER + ':' + PASSWORD + '@localhost:' + tlsProxyPort }, + }, +}; + +// Keeps the event loop alive until every scenario settles: a transport whose socket already died +// can otherwise leave the loop empty while the unref'd abort timer is still pending, and the +// process would exit before the signal fires. +const keepAlive = setInterval(() => {}, 250); + +// The child owns no listeners, so a TCP socket handle it still holds is one the transport did not +// release. Counted before the first request so the report is the transport's own, not the child's. +const openSockets = () => + process.getActiveResourcesInfo().filter((kind) => kind === 'TCPSocketWrap').length; +const baselineSockets = openSockets(); + +for (const scenario of scenarios) { + const spec = scenarioSpec[scenario]; + try { + const response = await requestApprovedUrl({ + url: new URL(spec.url), + approvedAddress: APPROVED_ADDRESS, + family: 4, + headers: {}, + signal: AbortSignal.timeout(4000), + environment: spec.environment, + }); + let body = ''; + for await (const chunk of response.body) body += Buffer.from(chunk).toString('utf8'); + const sni = response.headers['x-sni']; + await response.close(); + console.log(JSON.stringify({ + scenario, + outcome: 'response', + statusCode: response.statusCode, + body, + sniHeader: Array.isArray(sni) ? sni[0] : sni, + openSockets: openSockets() - baselineSockets, + })); + } catch (error) { + console.log(JSON.stringify({ + scenario, + outcome: 'rejection', + error: shape(error), + openSockets: openSockets() - baselineSockets, + })); + } +} +clearInterval(keepAlive); +process.exit(0); +`; +} diff --git a/packages/provision-kit/src/install-source-network-transport-proxy.test.ts b/packages/provision-kit/src/install-source-network-transport-proxy.test.ts new file mode 100644 index 0000000000..8316ed5678 --- /dev/null +++ b/packages/provision-kit/src/install-source-network-transport-proxy.test.ts @@ -0,0 +1,215 @@ +import assert from 'node:assert/strict'; +import path from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { afterAll, beforeAll, test } from 'vitest'; + +import { skipWhenLoopbackUnavailable } from '@agent-device/test-kit'; + +import * as nodeTransport from './install-source-network-transport.ts'; +import { resolveProxyForUrl } from './install-source-network-transport.ts'; +import { transportModulePath } from './install-source-network-transport-tls.fixtures.ts'; +import { + APPROVED_HOSTNAME, + ARTIFACT_BODY, + TRANSPORT_TEST_TIMEOUT_MS, +} from './install-source-network-transport.fixtures.ts'; +import { + EXPECTED_PROXY_AUTHORIZATION, + authHttpProxyEnvironment, + authProxyUrl, + observeProxyRequest, + runProxyAuthScenarios, + startProxyAuthLab, + type ProxyAuthLab, + type ProxyAuthScenario, +} from './install-source-network-transport-proxy.fixtures.ts'; + +const HERE = path.dirname(fileURLToPath(import.meta.url)); +const REPO_ROOT = path.resolve(HERE, '../../..'); + +/** Loopback certificate trusted by the child process; its subject names cover `localhost`. */ +const FIXTURE_CERTIFICATE = path.join( + REPO_ROOT, + 'test/integration/provider-scenarios/fixtures/localhost-cert.pem', +); + +let lab: ProxyAuthLab; + +beforeAll(async () => { + if (await skipWhenLoopbackUnavailable({ skip: () => {} }, 'install-source proxy-auth lab')) { + return; + } + lab = await startProxyAuthLab(REPO_ROOT); +}); + +afterAll(async () => { + await lab?.close(); +}); + +test('current routing passes an auth-bearing proxy URL through unchanged for both URL schemes', () => { + // Parity pin for the existing routing, not a NO_PROXY duplicate: the selected proxy URL keeps + // its scheme and userinfo verbatim, which is used to create a + // `Proxy-Authorization` header on CONNECT. + const httpProxy = authProxyUrl('http', 8080); + const tlsProxy = authProxyUrl('https', 8443); + assert.equal( + resolveProxyForUrl(new URL('http://example.net/app.zip'), { + http_proxy: httpProxy, + https_proxy: tlsProxy, + }), + httpProxy, + ); + assert.equal( + resolveProxyForUrl(new URL('https://example.net/app.zip'), { + http_proxy: httpProxy, + https_proxy: tlsProxy, + }), + tlsProxy, + ); +}); + +test(`an http-scheme proxy demanding fixture-only Basic auth completes the approved origin fetch`, async (t) => { + if (await skipWhenLoopbackUnavailable(t)) return; + const mark = lab.mark(); + const observed = await observeProxyRequest(nodeTransport, { + url: new URL(`http://${APPROVED_HOSTNAME}:${lab.originPort}/app.zip`), + signal: AbortSignal.timeout(TRANSPORT_TEST_TIMEOUT_MS), + environment: authHttpProxyEnvironment(lab.proxyPort), + lab, + caseDeadlineMs: TRANSPORT_TEST_TIMEOUT_MS + 500, + }); + + assert.equal(observed.outcome, 'response'); + assert.equal(observed.statusCode, 200); + assert.equal(observed.body, ARTIFACT_BODY); + assert.deepEqual(observed.connectAuthorities, ['127.0.0.1:']); + assert.deepEqual(observed.proxyAuthorizations, [EXPECTED_PROXY_AUTHORIZATION]); + assert.deepEqual(observed.originSaw, [ + { method: 'GET', url: '/app.zip', host: 'approved.invalid:' }, + ]); + assert.equal(observed.liveProxySockets, 0); + await lab.settleSince(mark); +}); + +test('an authenticated http-scheme proxy tunnels TLS to the approved origin under configured trust', async (t) => { + if (await skipWhenLoopbackUnavailable(t)) return; + const scenarios: ProxyAuthScenario[] = ['auth-http-proxy-tls-origin']; + const mark = lab.mark(); + const results = await runProxyAuthScenarios({ + subjectPath: transportModulePath(HERE), + originPort: lab.originPort, + tlsOriginPort: lab.tlsOriginPort, + proxyPort: lab.proxyPort, + tlsProxyPort: lab.tlsProxyPort, + scenarios, + trustFixtureCertificate: true, + fixtureCertificatePath: FIXTURE_CERTIFICATE, + }); + assert.deepEqual( + results, + [ + { + scenario: 'auth-http-proxy-tls-origin', + outcome: 'response', + statusCode: 200, + body: 'body', + sniHeader: 'localhost', + openSockets: 0, + }, + ], + `the CONNECT must carry the fixture credential, the tunnel must keep the URL host as SNI, and close must leave no socket of its own`, + ); + assert.deepEqual(lab.connectAuthoritiesSince(mark), ['127.0.0.1:']); + assert.deepEqual(lab.proxyAuthorizationsSince(mark), [EXPECTED_PROXY_AUTHORIZATION]); + await lab.settleSince(mark); +}); + +test( + 'TLS proxy scheme (https proxy URL): the downloader completes the authenticated fetch through the TLS proxy', + { timeout: 30_000 }, + async (t) => { + if (await skipWhenLoopbackUnavailable(t)) return; + + // Positive parity for the `https://` proxy scheme, run in a child so the loopback + // fixture certificate can be trusted: the proxy dial must be a TLS handshake under normal + // Node peer verification, then CONNECT carries the fixture credential + // to the approved address and the fetch returns the artifact bytes. + const mark = lab.mark(); + const results = await runProxyAuthScenarios({ + subjectPath: transportModulePath(HERE), + originPort: lab.originPort, + tlsOriginPort: lab.tlsOriginPort, + proxyPort: lab.proxyPort, + tlsProxyPort: lab.tlsProxyPort, + scenarios: ['auth-https-proxy-http-origin'], + trustFixtureCertificate: true, + fixtureCertificatePath: FIXTURE_CERTIFICATE, + }); + assert.deepEqual( + results, + [ + { + scenario: 'auth-https-proxy-http-origin', + outcome: 'response', + statusCode: 200, + body: ARTIFACT_BODY, + openSockets: 0, + }, + ], + `an https-scheme proxy with fixture Basic auth must complete the approved fetch and release the sockets it dialed`, + ); + assert.deepEqual(lab.connectAuthoritiesSince(mark), ['127.0.0.1:']); + assert.deepEqual(lab.proxyAuthorizationsSince(mark), [EXPECTED_PROXY_AUTHORIZATION]); + await lab.settleSince(mark); + assert.deepEqual(lab.proxySniSince(mark), [undefined]); + assert.equal(lab.liveProxySocketsSince(mark), 0); + }, +); + +test( + 'named TLS proxy (https proxy URL): the downloader finishes the TLS handshake, then CONNECT and the TLS origin fetch', + { timeout: 30_000 }, + async (t) => { + if (await skipWhenLoopbackUnavailable(t)) return; + + // Same `https://` proxy scheme with the proxy host written as a name rather than the loopback + // address, over a TLS origin. The proxy handshake must present that name as SNI, the CONNECT + // must then run inside the established TLS session and carry the fixture credential to the + // approved address, and the origin handshake must keep the URL host as SNI and return the + // artifact bytes. + const scenarios: ProxyAuthScenario[] = ['auth-named-https-proxy-tls-origin']; + const mark = lab.mark(); + const results = await runProxyAuthScenarios({ + subjectPath: transportModulePath(HERE), + originPort: lab.originPort, + tlsOriginPort: lab.tlsOriginPort, + proxyPort: lab.proxyPort, + tlsProxyPort: lab.tlsProxyPort, + scenarios, + trustFixtureCertificate: true, + fixtureCertificatePath: FIXTURE_CERTIFICATE, + }); + assert.deepEqual( + results, + [ + { + scenario: 'auth-named-https-proxy-tls-origin', + outcome: 'response', + statusCode: 200, + body: 'body', + sniHeader: 'localhost', + openSockets: 0, + }, + ], + `a named https-scheme proxy must complete the authenticated TLS origin fetch with the URL host as origin SNI and release the sockets it dialed`, + ); + assert.deepEqual( + lab.proxySniSince(mark), + ['localhost'], + `the proxy handshake must present the proxy host name as SNI`, + ); + assert.deepEqual(lab.connectAuthoritiesSince(mark), ['127.0.0.1:']); + assert.deepEqual(lab.proxyAuthorizationsSince(mark), [EXPECTED_PROXY_AUTHORIZATION]); + await lab.settleSince(mark); + }, +); diff --git a/packages/provision-kit/src/install-source-network-transport-tls.fixtures.ts b/packages/provision-kit/src/install-source-network-transport-tls.fixtures.ts new file mode 100644 index 0000000000..14eda3732d --- /dev/null +++ b/packages/provision-kit/src/install-source-network-transport-tls.fixtures.ts @@ -0,0 +1,141 @@ +import fs from 'node:fs/promises'; +import { execFile } from 'node:child_process'; +import { promisify } from 'node:util'; +import path from 'node:path'; + +import { mkdtempForTest } from './tmp-dir.fixtures.ts'; + +/** + * Runs the transport's TLS scenarios in a fresh process. + * + * TLS trust is fixed while a process starts, so a test worker cannot make itself trust the loopback + * fixture certificate; the caller passes `NODE_EXTRA_CA_CERTS` at spawn time. The child is written + * to a temporary file and owns no listeners, so the parent's loopback origin stays the single place + * where SNI names and CONNECT authorities are observed. + */ +export async function runTlsScenarios(params: { + /** Absolute path of the transport module the child imports. */ + subjectPath: string; + tlsOriginPort: number; + proxyPort: number; + scenarios: TlsScenario[]; + /** Trusts the loopback fixture certificate when true; the child rejects it when false. */ + trustFixtureCertificate: boolean; + fixtureCertificatePath: string; +}): Promise { + return await runTransportChild( + tlsChildSource(), + [ + params.subjectPath, + String(params.tlsOriginPort), + String(params.proxyPort), + ...params.scenarios, + ], + params.trustFixtureCertificate ? params.fixtureCertificatePath : '', + Math.max(1, params.scenarios.length) * 6_000, + ); +} + +export type TlsScenario = + | 'direct' + | 'proxied' + | 'proxied-literal-ip' + | 'direct-altname-mismatch' + | 'direct-literal-ip'; + +type TlsScenarioResult = { + scenario: TlsScenario; + outcome: 'response' | 'rejection'; + statusCode?: number; + body?: string; + /** The name the TLS origin saw at the handshake, echoed back by it. `'false'` means no SNI. */ + sniHeader?: string; + error?: { name?: string; code?: string | number; message?: string }; +}; + +export function transportModulePath(dir: string): string { + return path.join(dir, 'install-source-network-transport.ts'); +} + +/** + * The child's source. It is plain ESM so the child needs no loader: it imports the transport module + * by absolute path, which Node strips of types for a `.ts` target. + * + * The URL hostnames come from the caller's arguments: `argv[2]` is the transport module, then the + * TLS origin port, the proxy port, and the scenarios to run. + */ +function tlsChildSource(): string { + return ` +import { pathToFileURL } from 'node:url'; + +const [subjectPath, tlsOriginPort, proxyPort, ...scenarios] = process.argv.slice(2); +const { requestApprovedUrl } = await import(pathToFileURL(subjectPath).href); +const APPROVED_ADDRESS = '127.0.0.1'; + +const shape = (error) => ({ name: error?.name, code: error?.code, message: error?.message }); + +for (const scenario of scenarios) { + const proxied = scenario.startsWith('proxied'); + const literalIp = scenario.endsWith('literal-ip'); + const hostname = literalIp + ? APPROVED_ADDRESS + : scenario.includes('altname-mismatch') + ? 'elsewhere.invalid' + : 'localhost'; + const url = new URL('https://' + hostname + ':' + tlsOriginPort + '/artifact.bin'); + const environment = proxied + ? { HTTPS_PROXY: 'http://' + APPROVED_ADDRESS + ':' + proxyPort } + : { NO_PROXY: '*' }; + try { + const response = await requestApprovedUrl({ + url, + approvedAddress: APPROVED_ADDRESS, + family: 4, + headers: proxied ? { host: 'bad.example.test:' + tlsOriginPort } : {}, + signal: AbortSignal.timeout(4000), + environment, + }); + let body = ''; + for await (const chunk of response.body) body += Buffer.from(chunk).toString('utf8'); + const sni = response.headers['x-sni']; + console.log(JSON.stringify({ + scenario, + outcome: 'response', + statusCode: response.statusCode, + body, + sniHeader: Array.isArray(sni) ? sni[0] : sni, + })); + await response.close(); + } catch (error) { + console.log(JSON.stringify({ scenario, outcome: 'rejection', error: shape(error) })); + } +} +process.exit(0); +`; +} + +const execFileAsync = promisify(execFile); + +export async function runTransportChild( + source: string, + args: string[], + certificatePath: string, + timeout: number, +): Promise { + const dir = await mkdtempForTest('install-source-tls-child-'); + const childPath = path.join(dir, 'child.mjs'); + try { + await fs.writeFile(childPath, source, 'utf8'); + const { stdout } = await execFileAsync( + process.execPath, + ['--experimental-strip-types', childPath, ...args], + { env: { ...process.env, NODE_EXTRA_CA_CERTS: certificatePath }, timeout }, + ); + return stdout + .split('\n') + .filter((line) => line.startsWith('{')) + .map((line) => JSON.parse(line) as T); + } finally { + await fs.rm(dir, { recursive: true, force: true }); + } +} diff --git a/packages/provision-kit/src/install-source-network-transport.fixtures.ts b/packages/provision-kit/src/install-source-network-transport.fixtures.ts new file mode 100644 index 0000000000..6141b281ea --- /dev/null +++ b/packages/provision-kit/src/install-source-network-transport.fixtures.ts @@ -0,0 +1,516 @@ +import fs from 'node:fs'; +import http from 'node:http'; +import net from 'node:net'; +import tls from 'node:tls'; +import type { Duplex } from 'node:stream'; +import path from 'node:path'; + +import type { InstallSourceNetworkResponse } from './install-source-network-transport.ts'; + +/** + * Loopback-only harness for the install-source transport. + * + * Every listener binds 127.0.0.1, so no case leaves the machine. Origin hostnames are reserved + * bad names, so a request that reaches an origin proves the transport dialed the approved + * address it was handed rather than resolving the name. + */ + +/** Per-case budget: a stalled case must be cut short by the signal under test, not by Vitest. */ +export const TRANSPORT_TEST_TIMEOUT_MS = 2_000; + +/** Public test data for loopback HTTPS; the key is shared on purpose and is not a credential. */ +const LOOPBACK_TLS_FIXTURE_PATHS = { + cert: 'test/integration/provider-scenarios/fixtures/localhost-cert.pem', + key: 'test/integration/provider-scenarios/fixtures/localhost-key.pem', +} as const; + +export const APPROVED_HOSTNAME = 'approved.invalid'; +export const APPROVED_ADDRESS = '127.0.0.1'; +export const ARTIFACT_BODY = 'artifact'; + +const SETTLE_DEADLINE_MS = 700; +const SETTLE_POLL_MS = 20; + +export type ObservedRequest = { + method: string; + url: string; + host?: string; + custom?: string; +}; + +/** The transport surface a characterization run measures. */ +export type TransportSubject = { + requestApprovedUrl(params: { + url: URL; + approvedAddress: string; + family: 4 | 6; + headers: Record; + signal: AbortSignal; + environment: NodeJS.ProcessEnv; + }): Promise; +}; + +export type LoopbackLab = { + originPort: number; + tlsOriginPort: number; + /** Reachable origin the proxy refuses to dial: a working tunnel would answer 200 here. */ + refusalPort: number; + /** Origin that accepts a connection and never answers the request. */ + silentPort: number; + /** Origin that sends headers plus one chunk and then stalls. */ + stallerPort: number; + /** Reachable origin the proxy accepts for CONNECT and then never tunnels to. */ + stalledConnectPort: number; + proxyPort: number; + /** Counts recorded so far, to turn the lab's logs into per-case slices. */ + mark(): LabMark; + /** The requests the origin served after `mark`. */ + requestsSince(mark: LabMark): ObservedRequest[]; + connectAuthoritiesSince(mark: LabMark): string[]; + /** Live proxy sockets created after `mark`, so one case cannot be charged for another's. */ + liveProxySocketsSince(mark: LabMark): number; + /** Drops sockets the proxy still holds after a case that never settled. */ + dropProxySockets(): void; + /** + * Waits until the proxy holds no socket created after `mark`, bounded by SETTLE_DEADLINE_MS. A + * socket an earlier case leaked is not waited for: it is already reported against that case. + */ + settleSince(mark: LabMark): Promise; + close(): Promise; +}; + +type LabMark = { + requests: number; + connect: number; + proxySockets: number; +}; + +export function listen(server: net.Server): Promise { + return new Promise((resolve) => { + server.listen(0, APPROVED_ADDRESS, () => { + resolve((server.address() as net.AddressInfo).port); + }); + }); +} + +type TrackedSockets = { + /** Id given to the most recent connection, used as a per-case census mark. */ + highestId(): number; + /** Connections with an id above `since`, which is how a case counts only its own sockets. */ + liveSince(since: number): number; + destroyAll(): void; +}; + +export function trackSockets(server: net.Server): TrackedSockets { + const live = new Map(); + let ids = 0; + server.on('connection', (socket) => { + ids += 1; + live.set(socket, ids); + socket.on('close', () => live.delete(socket)); + socket.on('error', () => {}); + }); + return { + highestId: () => ids, + liveSince: (since) => [...live.values()].filter((id) => id > since).length, + destroyAll: () => { + for (const socket of live.keys()) socket.destroy(); + }, + }; +} + +export function readTlsFixturePair(root: string): { key: Buffer; cert: Buffer } { + return { + key: fs.readFileSync(path.join(root, LOOPBACK_TLS_FIXTURE_PATHS.key)), + cert: fs.readFileSync(path.join(root, LOOPBACK_TLS_FIXTURE_PATHS.cert)), + }; +} + +export function createTlsArtifactOrigin(credentials: { key: Buffer; cert: Buffer }): tls.Server { + return tls.createServer(credentials, (socket) => { + socket.on('error', () => {}); + socket.once('data', () => { + socket.end( + `HTTP/1.1 200 OK\r\nx-sni: ${String(socket.servername)}\r\ncontent-length: 4\r\n\r\nbody`, + ); + }); + }); +} + +export function forwardConnect(port: number, clientSocket: Duplex, head: Buffer): void { + const upstream = net.connect(port, APPROVED_ADDRESS, () => { + clientSocket.write('HTTP/1.1 200 Connection established\r\n\r\n'); + if (head.length > 0) upstream.write(head); + upstream.pipe(clientSocket); + clientSocket.pipe(upstream); + }); + upstream.on('error', () => clientSocket.destroy()); + clientSocket.on('error', () => upstream.destroy()); +} + +export async function startLoopbackLab(root: string): Promise { + const { key, cert } = readTlsFixturePair(root); + const requests: ObservedRequest[] = []; + const connectAuthorities: string[] = []; + + const origin = http.createServer((request, response) => { + requests.push({ + method: request.method ?? '', + url: request.url ?? '', + host: request.headers.host, + custom: request.headers['x-custom'] as string | undefined, + }); + if (request.url === '/redirect') { + response.writeHead(302, { location: 'http://cdn.invalid/final' }); + response.end(); + return; + } + response.setHeader('content-type', 'application/octet-stream'); + response.setHeader('x-repeated', ['a', 'b']); + response.setHeader('set-cookie', ['c=1', 'd=2']); + response.setHeader('x-origin-host', request.headers.host ?? ''); + response.writeHead(200); + response.end(ARTIFACT_BODY); + }); + const originSockets = trackSockets(origin); + const originPort = await listen(origin); + + const tlsOrigin = createTlsArtifactOrigin({ key, cert }); + const tlsSockets = trackSockets(tlsOrigin); + const tlsOriginPort = await listen(tlsOrigin); + + const refusal = http.createServer((_request, response) => { + response.writeHead(200); + response.end('refused-origin-was-reached'); + }); + const refusalSockets = trackSockets(refusal); + const refusalPort = await listen(refusal); + + const silent = http.createServer(() => {}); + const silentSockets = trackSockets(silent); + const silentPort = await listen(silent); + + const staller = http.createServer((_request, response) => { + response.writeHead(200, { 'content-type': 'text/plain' }); + response.write('partial-chunk'); + }); + const stallerSockets = trackSockets(staller); + const stallerPort = await listen(staller); + + const refusedPorts = new Set([refusalPort]); + + // Reachable origin used only for the stalled-CONNECT case: dialing it directly answers 200, so + // a response there would prove the tunnel was built when the proxy is meant to swallow it. + const stalledConnect = http.createServer((_request, response) => { + response.writeHead(200); + response.end('stalled-connect-origin-was-reached'); + }); + const stalledConnectSockets = trackSockets(stalledConnect); + const stalledConnectPort = await listen(stalledConnect); + const stalledConnectPorts = new Set([stalledConnectPort]); + + const proxy = http.createServer((_request, response) => { + response.writeHead(501).end(); + }); + const proxySockets = trackSockets(proxy); + proxy.on('connect', (request, clientSocket, head) => { + const authority = request.url ?? ''; + connectAuthorities.push(authority); + const port = Number(authority.split(':').at(-1)); + if (stalledConnectPorts.has(port)) { + clientSocket.once('end', () => clientSocket.destroy()); + clientSocket.resume(); + return; + } + if (refusedPorts.has(port)) { + clientSocket.write('HTTP/1.1 502 Bad Gateway\r\ncontent-length: 0\r\n\r\n'); + clientSocket.end(); + return; + } + forwardConnect(port, clientSocket, head); + }); + const proxyPort = await listen(proxy); + + return { + originPort, + tlsOriginPort, + refusalPort, + silentPort, + stallerPort, + stalledConnectPort, + proxyPort, + mark: () => ({ + requests: requests.length, + connect: connectAuthorities.length, + proxySockets: proxySockets.highestId(), + }), + requestsSince: (mark) => requestsWithoutPorts(requests.slice(mark.requests)), + connectAuthoritiesSince: (mark) => + authoritiesWithoutPorts(connectAuthorities.slice(mark.connect)), + liveProxySocketsSince: (mark) => proxySockets.liveSince(mark.proxySockets), + settleSince: async (mark) => { + const deadline = Date.now() + SETTLE_DEADLINE_MS; + while (Date.now() < deadline && proxySockets.liveSince(mark.proxySockets) > 0) { + await new Promise((resolve) => setTimeout(resolve, SETTLE_POLL_MS)); + } + }, + dropProxySockets: () => proxySockets.destroyAll(), + close: async () => { + for (const server of [origin, tlsOrigin, refusal, silent, staller, stalledConnect, proxy]) { + (server as http.Server).closeAllConnections?.(); + server.close(); + } + originSockets.destroyAll(); + tlsSockets.destroyAll(); + refusalSockets.destroyAll(); + silentSockets.destroyAll(); + stallerSockets.destroyAll(); + stalledConnectSockets.destroyAll(); + proxySockets.destroyAll(); + }, + }; +} + +export function directEnvironment(): NodeJS.ProcessEnv { + return { no_proxy: '*' }; +} + +export function proxiedEnvironment(proxyPort: number): NodeJS.ProcessEnv { + return { + http_proxy: `http://${APPROVED_ADDRESS}:${proxyPort}`, + https_proxy: `http://${APPROVED_ADDRESS}:${proxyPort}`, + }; +} + +export function noProxyEnvironment(proxyPort: number, hostname: string): NodeJS.ProcessEnv { + return { ...proxiedEnvironment(proxyPort), no_proxy: hostname }; +} + +type TransportOutcome = 'response' | 'rejection' | 'stream-interrupted' | 'hung'; + +type TransportObservation = { + outcome: TransportOutcome; + statusCode?: number; + body?: string; + headers?: Record; + /** Requests the origin served, with ephemeral ports removed. */ + originSaw?: ObservedRequest[]; + connectAuthorities?: string[]; + /** Proxy sockets this case created that its own close left alive. */ + liveProxySockets?: number; + error?: ErrorShape; + /** One entry per `close()` call: `'ok'`, or the error shape that call rejected with. */ + closeResults?: ('ok' | ErrorShape)[]; +}; + +export type ErrorShape = { + name?: string; + code?: string | number; + message?: string; + causeName?: string; + causeCode?: string | number; + causeMessage?: string; +}; + +export function errorShape(error: unknown): ErrorShape { + const shaped = error as + | (Error & { + code?: string | number; + cause?: Error & { code?: string | number }; + }) + | null; + const defined = (entries: [string, string | number | undefined][]): ErrorShape => + Object.fromEntries(entries.filter(([, value]) => value !== undefined)) as ErrorShape; + return defined([ + ['name', shaped?.name], + ['code', shaped?.code], + ['message', shaped?.message], + ['causeName', shaped?.cause?.name], + ['causeCode', shaped?.cause?.code], + ['causeMessage', shaped?.cause?.message], + ]); +} + +function selectedResponseHeaders( + headers: Record, +): Record { + const selected: Record = {}; + for (const name of [ + 'content-type', + 'x-repeated', + 'set-cookie', + 'x-origin-host', + 'x-sni', + 'location', + ]) { + const value = headers[name]; + if (value === undefined) continue; + const values = Array.isArray(value) ? value : [value]; + selected[name] = name === 'x-origin-host' ? values.map(withoutPort) : values; + } + return selected; +} + +export function approvedUrl(port: number, pathname = '/app.zip'): URL { + return new URL(`http://${APPROVED_HOSTNAME}:${port}${pathname}`); +} + +/** + * Runs one request through the subject and reports what happened instead of throwing: the + * response shape, the read result, the result of each `close()` call, and the proxy socket census + * after cleanup. + * + * Bound each transport operation independently and inspect sockets after the first close. + * Call close again to check that cleanup is idempotent. + */ +export async function observeRequest( + subject: TransportSubject, + params: { + url: URL; + approvedAddress?: string; + headers?: Record; + signal: AbortSignal; + environment: NodeJS.ProcessEnv; + lab: LoopbackLab; + readBody?: 'none'; + caseDeadlineMs?: number; + }, +): Promise { + const deadline = params.caseDeadlineMs ?? TRANSPORT_TEST_TIMEOUT_MS + 500; + type Step = { kind: 'ok'; value: T } | { kind: 'failed'; error: unknown } | { kind: 'hung' }; + const withinDeadline = async (work: Promise): Promise> => { + return await Promise.race([ + work.then( + (value) => ({ kind: 'ok', value }) as Step, + (error: unknown) => ({ kind: 'failed', error }) as Step, + ), + new Promise>((resolve) => { + const timer = setTimeout(() => resolve({ kind: 'hung' }), deadline); + timer.unref?.(); + }), + ]); + }; + + const mark = params.lab.mark(); + const closeResults: ('ok' | ErrorShape)[] = []; + + const hang = async (): Promise => { + await params.lab.settleSince(mark); + const observation = { + outcome: 'hung' as const, + connectAuthorities: params.lab.connectAuthoritiesSince(mark), + liveProxySockets: params.lab.liveProxySocketsSince(mark), + closeResults, + }; + // The case reports the socket it left behind; the lab then drops it so the next case's + // census measures that case's own cleanup. + params.lab.dropProxySockets(); + await params.lab.settleSince(mark); + return observation; + }; + + const started = await withinDeadline( + subject.requestApprovedUrl({ + url: params.url, + approvedAddress: params.approvedAddress ?? APPROVED_ADDRESS, + family: 4, + headers: params.headers ?? {}, + signal: params.signal, + environment: params.environment, + }), + ); + if (started.kind === 'hung') return await hang(); + if (started.kind === 'failed') { + await params.lab.settleSince(mark); + return { + outcome: 'rejection', + connectAuthorities: params.lab.connectAuthoritiesSince(mark), + liveProxySockets: params.lab.liveProxySocketsSince(mark), + closeResults, + error: errorShape(started.error), + }; + } + const response = started.value; + const closeOnce = async () => { + try { + await response.close(); + closeResults.push('ok'); + } catch (error) { + closeResults.push(errorShape(error)); + } + }; + + let body = ''; + let readError: ErrorShape | undefined; + if (params.readBody !== 'none') { + const read = await withinDeadline(readStream(response.body)); + if (read.kind === 'hung') { + await closeOnce(); + return { ...(await hang()), closeResults }; + } + if (read.kind === 'ok') { + body = read.value.body; + readError = read.value.error; + } else { + readError = errorShape(read.error); + } + } + + await closeOnce(); + await params.lab.settleSince(mark); + const liveProxySockets = params.lab.liveProxySocketsSince(mark); + await closeOnce(); + await params.lab.settleSince(mark); + return { + outcome: readError ? 'stream-interrupted' : 'response', + statusCode: response.statusCode, + body, + headers: selectedResponseHeaders(response.headers), + originSaw: params.lab.requestsSince(mark), + connectAuthorities: params.lab.connectAuthoritiesSince(mark), + liveProxySockets, + error: readError, + closeResults, + }; +} + +async function readStream( + body: NodeJS.ReadableStream, +): Promise<{ body: string; error?: ErrorShape }> { + const iterable = body as AsyncIterable; + const chunks: Buffer[] = []; + try { + for await (const chunk of iterable) { + chunks.push(Buffer.from(chunk)); + } + } catch (error) { + return { body: Buffer.concat(chunks).toString('utf8'), error: errorShape(error) }; + } + return { body: Buffer.concat(chunks).toString('utf8') }; +} + +/** Signal aborted with an operator reason after a bounded delay. */ +export function operatorAbortAfter(ms: number): AbortSignal { + const controller = new AbortController(); + const timer = setTimeout(() => controller.abort(new Error('operator stop')), ms); + timer.unref?.(); + return controller.signal; +} + +/** Drops ephemeral ports from what the origin recorded so an observation is stable to compare. */ +export function requestsWithoutPorts(requests: ObservedRequest[]): ObservedRequest[] { + return requests.map((request) => ({ + ...request, + url: withoutPort(request.url), + host: request.host === undefined ? undefined : withoutPort(request.host), + })); +} + +/** Drops the ephemeral port from a CONNECT authority so an observation is stable to compare. */ +export function authoritiesWithoutPorts(authorities: string[]): string[] { + return authorities.map(withoutPort); +} + +function withoutPort(value: string): string { + return value.replaceAll(/:\d+/g, ':'); +} diff --git a/packages/provision-kit/src/install-source-network-transport.test.ts b/packages/provision-kit/src/install-source-network-transport.test.ts index 8cef10cca9..72cd75ee14 100644 --- a/packages/provision-kit/src/install-source-network-transport.test.ts +++ b/packages/provision-kit/src/install-source-network-transport.test.ts @@ -1,4 +1,5 @@ import assert from 'node:assert/strict'; +import { once } from 'node:events'; import http from 'node:http'; import net from 'node:net'; import type { AddressInfo } from 'node:net'; @@ -406,3 +407,40 @@ test('a loopback body that stalls after accepted bytes expires at the inactivity await closeServer(server); } }); + +test.for(['headers', 'body'] as const)('a TCP reset during %s keeps ECONNRESET', async (phase) => { + let peer: net.Socket | undefined; + const server = http.createServer((request, response) => { + peer = request.socket; + if (phase === 'headers') peer.resetAndDestroy(); + else response.write('partial'); + }); + const port = await listen(server); + try { + const response = requestApprovedUrl({ + url: new URL(`http://approved.invalid:${port}/app.apk`), + approvedAddress: '127.0.0.1', + family: 4, + headers: {}, + signal: AbortSignal.timeout(5_000), + environment: {}, + }); + if (phase === 'headers') { + await assert.rejects(response, { code: 'ECONNRESET' }); + return; + } + const { body, close } = await response; + try { + const [chunk] = await once(body, 'data'); + assert.equal(String(chunk), 'partial'); + const error = once(body, 'error'); + peer!.resetAndDestroy(); + const [failure] = await error; + assert.equal(failure.code, 'ECONNRESET'); + } finally { + await close(); + } + } finally { + await closeServer(server); + } +}); diff --git a/packages/provision-kit/src/install-source-network-transport.ts b/packages/provision-kit/src/install-source-network-transport.ts index dec224debb..c379d86184 100644 --- a/packages/provision-kit/src/install-source-network-transport.ts +++ b/packages/provision-kit/src/install-source-network-transport.ts @@ -1,5 +1,8 @@ -import net from 'node:net'; -import { Agent, Pool, ProxyAgent, request, type Dispatcher } from 'undici'; +import { once } from 'node:events'; +import http from 'node:http'; +import https from 'node:https'; +import net, { type Socket } from 'node:net'; +import tls from 'node:tls'; export type InstallSourceNetworkResponse = { statusCode: number; @@ -16,43 +19,146 @@ export async function requestApprovedUrl(params: { signal: AbortSignal; /** The host environment whose proxy variables apply to the request. */ environment: NodeJS.ProcessEnv; - /** Called once the dispatcher's connection to the upstream is established. */ + /** Called once the upstream TCP connection or TLS session is established. */ onConnected?: () => void; }): Promise { - const proxy = resolveProxyForUrl(params.url, params.environment); - const dispatcher = proxy - ? proxyDispatcher(proxy, params.url, params.onConnected) - : directDispatcher(params.approvedAddress, params.family); - const dispatchUrl = proxy - ? approvedAddressUrl(params.url, params.approvedAddress, params.family) - : params.url; - // Only undici's Agent emits 'connect' (pinned undici 7.30.1: agent.js/client.js do, the - // ProxyAgent dispatcher does not), so the proxy path reports establishment from inside its own - // tunnel connector wrap instead of this event. - if (!proxy && params.onConnected) dispatcher.once('connect', params.onConnected); + const { url, approvedAddress, signal } = params; + signal.throwIfAborted(); + const hostname = stripBrackets(url.hostname); + const secure = url.protocol === 'https:'; + const port = Number(url.port || (secure ? 443 : 80)); + const proxy = resolveProxyForUrl(url, params.environment); + const authority = + params.family === 6 ? `[${approvedAddress}]:${port}` : `${approvedAddress}:${port}`; + const tunnel = proxy ? await connectThroughProxy(new URL(proxy), authority, signal) : undefined; + const socket = secure + ? tls.connect({ + ...(tunnel ? { socket: tunnel } : { host: approvedAddress, port }), + ...(net.isIP(hostname) === 0 ? { servername: hostname } : {}), + checkServerIdentity: (_host, certificate) => tls.checkServerIdentity(hostname, certificate), + }) + : (tunnel ?? net.connect({ host: approvedAddress, port })); + let request: http.ClientRequest | undefined; + let body: http.IncomingMessage | undefined; + const onAbort = () => { + const reason: unknown = signal.reason; + const error = + reason instanceof Error + ? reason + : new Error('Install source request aborted', { + cause: reason, + }); + if (body && !body.readableEnded) body.destroy(error); + else if (!body && request) request.destroy(error); + else if (!request) socket.destroy(error); + }; + signal.addEventListener('abort', onAbort, { once: true }); + const close = async () => { + signal.removeEventListener('abort', onAbort); + body?.destroy(); + await Promise.all([closeSocket(socket), tunnel && tunnel !== socket && closeSocket(tunnel)]); + }; try { - const requestOptions = { - dispatcher, - headers: proxy ? { ...params.headers, host: params.url.host } : params.headers, - maxRedirections: 0, - method: 'GET' as const, - signal: params.signal, - }; - const response = await request(dispatchUrl, requestOptions); - return { - statusCode: response.statusCode, - headers: response.headers, - body: response.body, - close: async () => await closeDispatcher(dispatcher), - }; + if (!tunnel || secure) await once(socket, secure ? 'secureConnect' : 'connect'); + signal.throwIfAborted(); + params.onConnected?.(); + // A connected socket (including a TLS socket) carries the request without a shared agent. + request = http.request({ + method: 'GET', + path: `${url.pathname}${url.search}`, + headers: { ...params.headers, host: url.host, connection: 'close' }, + createConnection: () => socket, + }); + const upstream = request; + return await new Promise((resolve, reject) => { + upstream.on('error', (error) => { + if (body) body.destroy(error); + else reject(error); + }); + upstream.once('response', (response) => { + body = response; + // The download can reject the response before attaching its body pipeline. + response.on('error', () => {}); + resolve({ + statusCode: response.statusCode ?? 0, + headers: response.headersDistinct, + body: response, + close, + }); + }); + upstream.once('upgrade', () => reject(networkError('Unexpected upgrade response', 'EPROTO'))); + upstream.end(); + }); + } catch (error) { + await close(); + throw error; + } +} + +async function connectThroughProxy( + proxy: URL, + authority: string, + signal: AbortSignal, +): Promise { + const request = createProxyConnectRequest(proxy, authority); + const onAbort = () => request.destroy(); + signal.addEventListener('abort', onAbort, { once: true }); + try { + const connected = once(request, 'connect') as Promise<[http.IncomingMessage, Socket, Buffer]>; + request.end(); + const [response, socket, head] = await connected; + if (signal.aborted || response.statusCode !== 200) { + await closeSocket(socket); + signal.throwIfAborted(); + throw networkError( + `Proxy response (${response.statusCode}) !== 200 when HTTP Tunneling`, + 'EPROXYTUNNEL', + ); + } + if (head.length) socket.unshift(head); + return socket; } catch (error) { - await closeDispatcher(dispatcher); + if (request.socket) await closeSocket(request.socket); + signal.throwIfAborted(); throw error; } finally { - if (!proxy && params.onConnected) dispatcher.off('connect', params.onConnected); + signal.removeEventListener('abort', onAbort); } } +function createProxyConnectRequest(proxy: URL, authority: string): http.ClientRequest { + const secure = proxy.protocol === 'https:'; + if (!secure && proxy.protocol !== 'http:') { + throw new Error('Unsupported install source proxy protocol'); + } + const headers: Record = { host: authority }; + if (proxy.username || proxy.password) { + const credentials = `${decodeURIComponent(proxy.username)}:${decodeURIComponent(proxy.password)}`; + headers['proxy-authorization'] = `Basic ${Buffer.from(credentials).toString('base64')}`; + } + const hostname = stripBrackets(proxy.hostname); + return (secure ? https : http).request({ + hostname, + port: Number(proxy.port || (secure ? 443 : 80)), + method: 'CONNECT', + path: authority, + headers, + agent: false, + ...(secure ? { servername: net.isIP(hostname) ? '' : hostname } : {}), + }); +} + +function networkError(message: string, code: string): Error { + return Object.assign(new Error(message), { code }); +} + +async function closeSocket(socket: Socket): Promise { + if (socket.closed) return; + const closed = new Promise((resolve) => socket.once('close', resolve)); + socket.destroy(); + await closed; +} + export function resolveProxyForUrl(url: URL, environment: NodeJS.ProcessEnv): string | undefined { const noProxy = environment.no_proxy ?? environment.NO_PROXY; if (matchesNoProxy(url, noProxy)) return undefined; @@ -78,67 +184,6 @@ export function matchesNoProxy(url: URL, raw: string | undefined): boolean { }); } -function directDispatcher(address: string, family: 4 | 6): Agent { - return new Agent({ - connect: { - lookup: (_hostname, options, callback) => { - if (options.all) { - callback(null, [{ address, family }]); - return; - } - callback(null, address, family); - }, - }, - }); -} - -function proxyDispatcher(proxyUrl: string, destination: URL, onConnected?: () => void): ProxyAgent { - const literalDestination = net.isIP(stripBrackets(destination.hostname)) !== 0; - return new ProxyAgent({ - uri: proxyUrl, - proxyTunnel: true, - requestTls: - destination.protocol === 'https:' && !literalDestination - ? { servername: stripBrackets(destination.hostname) } - : undefined, - // ProxyAgent builds its own inner Agent and never emits 'connect' (pinned undici 7.30.1, - // lib/dispatcher/proxy-agent.js), so establishment is reported by wrapping the tunnel - // connector the inner factory receives: its callback fires exactly when the upstream - // connection through the CONNECT tunnel is established. - factory: (origin: string | URL, options: Pool.Options) => - new Pool(origin, withUpstreamConnectedCallback(options, onConnected)), - }); -} - -type TunnelConnectCallback = ( - ...args: [error: null, socket: net.Socket] | [error: Error, socket: null] -) => void; -type TunnelConnect = (options: unknown, callback: TunnelConnectCallback) => void; - -/** Fires `onConnected` once the wrapped connector has established the upstream connection. */ -function withUpstreamConnectedCallback( - options: Pool.Options, - onConnected?: () => void, -): Pool.Options { - const connect = options.connect; - if (!onConnected || typeof connect !== 'function') return options; - const tunnelConnect = connect as TunnelConnect; - return { - ...options, - connect: (connectOptions: unknown, callback: TunnelConnectCallback) => - tunnelConnect(connectOptions, (...args) => { - if (args[0] === null) onConnected(); - callback(...args); - }), - }; -} - -function approvedAddressUrl(original: URL, address: string, family: 4 | 6): URL { - const approved = new URL(original); - approved.hostname = family === 6 ? `[${stripBrackets(address)}]` : address; - return approved; -} - function parseNoProxyToken(token: string): { hostname: string; port?: string } { if (token.startsWith('[')) { const close = token.indexOf(']'); @@ -158,7 +203,3 @@ function parseNoProxyToken(token: string): { hostname: string; port?: string } { function stripBrackets(value: string): string { return value.startsWith('[') && value.endsWith(']') ? value.slice(1, -1) : value; } - -async function closeDispatcher(dispatcher: Dispatcher): Promise { - await dispatcher.close(); -} diff --git a/packages/provision-kit/tsconfig.json b/packages/provision-kit/tsconfig.json index 247a915b90..4ddd6ceaf5 100644 --- a/packages/provision-kit/tsconfig.json +++ b/packages/provision-kit/tsconfig.json @@ -10,5 +10,18 @@ "tsBuildInfoFile": "./dist-types/index.tsbuildinfo" }, "include": ["src"], - "references": [{ "path": "../contracts" }, { "path": "../host-kit" }, { "path": "../kernel" }] + "references": [ + { + "path": "../contracts" + }, + { + "path": "../host-kit" + }, + { + "path": "../kernel" + }, + { + "path": "../test-kit" + } + ] } diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index ea43727f42..6ba27f4031 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -1138,12 +1138,12 @@ importers: specifier: workspace:* version: link:../kernel devDependencies: + '@agent-device/test-kit': + specifier: workspace:* + version: link:../test-kit ipaddr.js: specifier: ^2.5.0 version: 2.5.0 - undici: - specifier: 7.30.1 - version: 7.30.1 packages/proxy: devDependencies: diff --git a/website/docs/docs/commands.md b/website/docs/docs/commands.md index 24f802546f..af81e92037 100644 --- a/website/docs/docs/commands.md +++ b/website/docs/docs/commands.md @@ -1728,6 +1728,7 @@ agent-device install-from-source https://example.com/builds/app.aab --platform a - `install-from-source` allows 600 seconds overall, including up to 120 seconds for the download. The local Android and iOS install limits match `install`. - A URL may point to an Android `.apk` or `.aab`, or, from any public host, to an archive containing one `.apk`, `.aab`, `.ipa`, or iOS `.app`. - Repeat `--header ` for authenticated or signed downloads. Sensitive headers are not forwarded to other origins. +- For a network failure during the download, `--json` reports `COMMAND_FAILED` with the system code in `error.details.networkErrorCode` when available. A phase timeout reports `connect-timeout`, `header-timeout`, or `body-timeout` in the same field. A caller cancellation has its own error reason. - `--retain-paths` keeps the downloaded and extracted files for 15 minutes. Use `--retention-ms ` to set an integer duration from 1 to 2,147,483,647 milliseconds. - Limits: at most five redirects, no HTTPS-to-HTTP downgrade, 2 GiB download, 4 GiB extracted, 100,000 entries, and three nested archive layers. Links and special archive entries are rejected. `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` are honored. These match the Node.js client's `installFromSource()` checks. From a4a0f5cad6a5b80fa00220045c63c97b5a153187 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sun, 22 Nov 2026 12:57:28 +0100 Subject: [PATCH 2/6] fix(provision-kit): keep the source URL refusal when the host does not resolve --- .../src/install-source-download.test.ts | 26 +++++++++++++++++++ .../src/install-source-download.ts | 11 +++++++- 2 files changed, 36 insertions(+), 1 deletion(-) diff --git a/packages/provision-kit/src/install-source-download.test.ts b/packages/provision-kit/src/install-source-download.test.ts index 078a3138a0..d21d243a3b 100644 --- a/packages/provision-kit/src/install-source-download.test.ts +++ b/packages/provision-kit/src/install-source-download.test.ts @@ -492,3 +492,29 @@ test('download and the trusted-source check refuse an unparsable source alike', ); assert.throws(() => isTrustedInstallSourceUrl(source), expected); }); + +test('download keeps the INVALID_ARGS refusal and hint when the source host does not resolve', async () => { + const tempRoot = await mkdtempForTest('agent-device-download-dns-'); + const lookup = vi + .spyOn(dns, 'lookup') + .mockRejectedValue(Object.assign(new Error('getaddrinfo ENOTFOUND'), { code: 'ENOTFOUND' })); + const requester = vi.spyOn(networkTransport, 'requestApprovedUrl'); + try { + const error = await downloadInstallSource({ + tempDir: tempRoot, + url: 'https://typo.example/app.apk', + signal: new AbortController().signal, + environment: {}, + }).catch((error: unknown) => error); + + assert.ok(error instanceof AppError); + assert.equal(error.code, 'INVALID_ARGS'); + assert.equal(error.details?.hint, 'Use a public artifact URL.'); + assert.equal(error.details?.networkErrorCode, undefined); + assert.equal(requester.mock.calls.length, 0); + } finally { + requester.mockRestore(); + lookup.mockRestore(); + await fs.rm(tempRoot, { recursive: true, force: true }); + } +}); diff --git a/packages/provision-kit/src/install-source-download.ts b/packages/provision-kit/src/install-source-download.ts index cf98a941a8..399b6e195e 100644 --- a/packages/provision-kit/src/install-source-download.ts +++ b/packages/provision-kit/src/install-source-download.ts @@ -103,8 +103,17 @@ async function requestHop( environment: NodeJS.ProcessEnv, ): Promise { const { watchdog } = phases; + let approved: Awaited>; + try { + approved = await approveDownloadSourceUrl(url, watchdog.signal); + } catch (error) { + // An approval refusal is a typed answer about the URL, not a transport failure. + throw ( + phaseTimeout(error, phases) ?? + (isSignalFailure(error, watchdog.signal) ? watchdog.signal.reason : error) + ); + } try { - const approved = await approveDownloadSourceUrl(url, watchdog.signal); return await networkTransport.requestApprovedUrl({ url, approvedAddress: approved.address, From 22cff6bc715783f38fdc37d44cad0df6f3946e03 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sun, 22 Nov 2026 13:07:58 +0100 Subject: [PATCH 3/6] fix(provision-kit): keep a typed cancellation that wraps the signal reason --- .../src/install-source-download.test.ts | 34 +++++++++++++++++++ .../src/install-source-download.ts | 2 ++ 2 files changed, 36 insertions(+) diff --git a/packages/provision-kit/src/install-source-download.test.ts b/packages/provision-kit/src/install-source-download.test.ts index d21d243a3b..d33ce551af 100644 --- a/packages/provision-kit/src/install-source-download.test.ts +++ b/packages/provision-kit/src/install-source-download.test.ts @@ -518,3 +518,37 @@ test('download keeps the INVALID_ARGS refusal and hint when the source host does await fs.rm(tempRoot, { recursive: true, force: true }); } }); + +test('download keeps the typed cancellation when the caller aborts during URL approval', async () => { + const tempRoot = await mkdtempForTest('agent-device-download-approval-abort-'); + const controller = new AbortController(); + let releaseLookup: () => void = () => {}; + const lookup = vi.spyOn(dns, 'lookup').mockImplementation( + async () => + await new Promise>>((resolve) => { + releaseLookup = () => + resolve([{ address: '93.184.216.34', family: 4 }] as unknown as Awaited< + ReturnType + >); + queueMicrotask(() => controller.abort()); + }), + ); + const requester = vi.spyOn(networkTransport, 'requestApprovedUrl'); + try { + const error = await downloadInstallSource({ + tempDir: tempRoot, + url: 'https://example.com/app.apk', + signal: controller.signal, + environment: {}, + }).catch((error: unknown) => error); + + assert.ok(error instanceof AppError); + assert.ok(isRequestCanceledError(error)); + assert.equal(requester.mock.calls.length, 0); + } finally { + releaseLookup(); + requester.mockRestore(); + lookup.mockRestore(); + await fs.rm(tempRoot, { recursive: true, force: true }); + } +}); diff --git a/packages/provision-kit/src/install-source-download.ts b/packages/provision-kit/src/install-source-download.ts index 399b6e195e..255891687e 100644 --- a/packages/provision-kit/src/install-source-download.ts +++ b/packages/provision-kit/src/install-source-download.ts @@ -152,9 +152,11 @@ function phaseTimeout(error: unknown, phases: TransferPhaseTools): AppError | un ); } +/** A raw failure from the watchdog signal. A typed error that wraps the signal reason keeps its type. */ function isSignalFailure(error: unknown, signal: AbortSignal): boolean { return ( signal.aborted && + !(error instanceof AppError) && (error === signal.reason || (error instanceof Error && error.cause === signal.reason)) ); } From 39fc97125339f0e5a74cd96bb8b4f116d05e4281 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sun, 22 Nov 2026 14:16:24 +0100 Subject: [PATCH 4/6] fix(provision-kit): offer http/1.1 ALPN on both downloader TLS legs The Node HTTP transport handed `tls.connect` and the HTTPS CONNECT request no `ALPNProtocols`, while the base Undici connector offered `http/1.1`. An origin or proxy that requires a negotiated protocol now refuses a transfer that used to work. Offer `http/1.1` on the origin connection and on the proxy CONNECT request. The loopback TLS origin and the TLS CONNECT proxy advertise `http/1.1`, so each handshake reports what the transport offered: the origin echoes the negotiated protocol, and the proxy records it at `secureConnection`. Dropping either production option fails that leg's assertion. --- ...-source-network-transport-loopback.test.ts | 25 +++++++--- ...source-network-transport-proxy.fixtures.ts | 50 +++++++++++++++---- ...all-source-network-transport-proxy.test.ts | 16 +++++- ...l-source-network-transport-tls.fixtures.ts | 7 +++ ...stall-source-network-transport.fixtures.ts | 16 +++++- .../src/install-source-network-transport.ts | 9 +++- 6 files changed, 99 insertions(+), 24 deletions(-) diff --git a/packages/provision-kit/src/install-source-network-transport-loopback.test.ts b/packages/provision-kit/src/install-source-network-transport-loopback.test.ts index b238f5d851..04da99aa41 100644 --- a/packages/provision-kit/src/install-source-network-transport-loopback.test.ts +++ b/packages/provision-kit/src/install-source-network-transport-loopback.test.ts @@ -258,12 +258,12 @@ test(`a proxy that never answers CONNECT is closed on caller cancellation`, asyn assert.equal(observed.liveProxySockets, 0); }); -test('The downloader derives TLS trust, SNI, and the certificate identity check from the URL host', async (t) => { +test('The downloader derives TLS trust, SNI, ALPN, and the certificate identity check from the URL host', async (t) => { if (await skipWhenLoopbackUnavailable(t)) return; // TLS trust is fixed when a process starts, so the test runs the TLS scenarios in a child // process spawned with the loopback fixture certificate as an extra CA. The child owns no - // listeners: the parent's TLS origin echoes the SNI name it saw, and that is how the dial is - // verified. + // listeners: the parent's TLS origin echoes the SNI name and the negotiated protocol it saw, and + // that is how the dial is verified. const scenarios: TlsScenario[] = [ 'direct', 'proxied', @@ -283,18 +283,27 @@ test('The downloader derives TLS trust, SNI, and the certificate identity check // SNI names the URL host, so the server answers with that name. A literal IP cannot be an SNI // name, and the client omits it there; the fixture certificate covers `127.0.0.1` as an IP - // subject alternative name, so those connections still complete. - const expectedSni: [TlsScenario, string][] = [ + // subject alternative name, so those connections still complete. The origin advertises + // `http/1.1`, so the echoed protocol proves the origin leg offered the protocol the transport + // speaks; an origin reports `false` for a client that offers none. + const expectedOriginHandshake: [TlsScenario, string][] = [ ['direct', 'localhost'], ['proxied', 'localhost'], ['proxied-literal-ip', 'false'], ['direct-literal-ip', 'false'], ]; - for (const [scenario, sniHeader] of expectedSni) { + for (const [scenario, sniHeader] of expectedOriginHandshake) { assert.deepEqual( { scenario, ...byScenario.get(scenario) }, - { scenario, outcome: 'response', statusCode: 200, body: 'body', sniHeader }, - 'a trusted loopback certificate must complete the request with the URL host as SNI', + { + scenario, + outcome: 'response', + statusCode: 200, + body: 'body', + sniHeader, + alpnHeader: 'http/1.1', + }, + 'a trusted loopback certificate must complete the request with the URL host as SNI and must negotiate HTTP/1.1 at the origin', ); } assert.equal( diff --git a/packages/provision-kit/src/install-source-network-transport-proxy.fixtures.ts b/packages/provision-kit/src/install-source-network-transport-proxy.fixtures.ts index aa06baa2f7..376f832eef 100644 --- a/packages/provision-kit/src/install-source-network-transport-proxy.fixtures.ts +++ b/packages/provision-kit/src/install-source-network-transport-proxy.fixtures.ts @@ -10,6 +10,7 @@ import { authoritiesWithoutPorts, createTlsArtifactOrigin, errorShape, + FIXTURE_ALPN_PROTOCOLS, forwardConnect, listen, readTlsFixturePair, @@ -57,7 +58,7 @@ export function authHttpProxyEnvironment(proxyPort: number): NodeJS.ProcessEnv { type ProxyAuthLabMark = { requests: number; connect: number; - proxySni: number; + proxyHandshakes: number; plainProxySockets: number; tlsProxySockets: number; }; @@ -75,6 +76,8 @@ export type ProxyAuthLab = { proxyAuthorizationsSince(mark: ProxyAuthLabMark): (string | undefined)[]; /** The SNI names the TLS proxy accepted at its handshakes, after `mark`. */ proxySniSince(mark: ProxyAuthLabMark): (string | undefined)[]; + /** The ALPN protocols the TLS proxy negotiated at its handshakes, after `mark`. */ + proxyAlpnSince(mark: ProxyAuthLabMark): (string | undefined)[]; liveProxySocketsSince(mark: ProxyAuthLabMark): number; settleSince(mark: ProxyAuthLabMark): Promise; dropProxySockets(): void; @@ -84,6 +87,13 @@ export type ProxyAuthLab = { const SETTLE_DEADLINE_MS = 700; const SETTLE_POLL_MS = 20; +/** What the TLS proxy observed at one client handshake. */ +type TlsProxyHandshake = { + sni: string | undefined; + /** The negotiated protocol; `undefined` when the handshake negotiated none. */ + alpn: string | undefined; +}; + /** One CONNECT exchange: demand the fixture credential, then tunnel to the approved address. */ function handleConnect( record: { authorities: string[]; authorizations: (string | undefined)[] }, @@ -106,7 +116,7 @@ function handleConnect( export async function startProxyAuthLab(root: string): Promise { const { key, cert } = readTlsFixturePair(root); const requests: ObservedRequest[] = []; - const proxySni: (string | undefined)[] = []; + const proxyHandshakes: TlsProxyHandshake[] = []; const record = { authorities: [] as string[], authorizations: [] as (string | undefined)[] }; const origin = http.createServer((request, response) => { @@ -132,18 +142,26 @@ export async function startProxyAuthLab(root: string): Promise { const proxySockets = trackSockets(proxy); const proxyPort = await listen(proxy); - // The same CONNECT proxy behind TLS: an `https://` proxy URL must reach this listener. - const tlsProxyServer = https.createServer({ key, cert }, (_request, response) => { - response.writeHead(501).end(); - }); + // The same CONNECT proxy behind TLS: an `https://` proxy URL must reach this listener. It + // advertises the fixture ALPN protocols, so the handshake can evidence what the client offered. + const tlsProxyServer = https.createServer( + { key, cert, ALPNProtocols: FIXTURE_ALPN_PROTOCOLS }, + (_request, response) => { + response.writeHead(501).end(); + }, + ); tlsProxyServer.on('connect', (request, clientSocket, head) => handleConnect(record, request, clientSocket, head), ); tlsProxyServer.on('tlsClientError', () => {}); - // Records the name each client asked for at the handshake, so a case can prove the proxy dial - // presented the proxy host as SNI. A handshake without SNI records `undefined`. + // Records what each client presented at the handshake, so a case can prove the proxy dial offered + // the proxy host as SNI and offered the transport's application protocol. A handshake without SNI + // or without a negotiated protocol records `undefined`. tlsProxyServer.on('secureConnection', (socket) => - proxySni.push(typeof socket.servername === 'string' ? socket.servername : undefined), + proxyHandshakes.push({ + sni: typeof socket.servername === 'string' ? socket.servername : undefined, + alpn: typeof socket.alpnProtocol === 'string' ? socket.alpnProtocol : undefined, + }), ); const tlsProxySockets = trackSockets(tlsProxyServer); const tlsProxyPort = await listen(tlsProxyServer); @@ -156,7 +174,7 @@ export async function startProxyAuthLab(root: string): Promise { mark: () => ({ requests: requests.length, connect: record.authorities.length, - proxySni: proxySni.length, + proxyHandshakes: proxyHandshakes.length, plainProxySockets: proxySockets.highestId(), tlsProxySockets: tlsProxySockets.highestId(), }), @@ -164,7 +182,10 @@ export async function startProxyAuthLab(root: string): Promise { connectAuthoritiesSince: (mark) => authoritiesWithoutPorts(record.authorities.slice(mark.connect)), proxyAuthorizationsSince: (mark) => record.authorizations.slice(mark.connect), - proxySniSince: (mark) => proxySni.slice(mark.proxySni), + proxySniSince: (mark) => + proxyHandshakes.slice(mark.proxyHandshakes).map((handshake) => handshake.sni), + proxyAlpnSince: (mark) => + proxyHandshakes.slice(mark.proxyHandshakes).map((handshake) => handshake.alpn), liveProxySocketsSince: (mark) => proxySockets.liveSince(mark.plainProxySockets) + tlsProxySockets.liveSince(mark.tlsProxySockets), @@ -278,6 +299,11 @@ type ProxyAuthScenarioResult = { statusCode?: number; body?: string; sniHeader?: string; + /** + * The protocol the TLS origin negotiated, echoed back by it. `'false'` means the handshake + * negotiated none, which is what an origin reports for a client that offers none. + */ + alpnHeader?: string; error?: ErrorShape; /** * Child TCP resources remaining above the initial process count. Use one scenario per child @@ -389,6 +415,7 @@ for (const scenario of scenarios) { let body = ''; for await (const chunk of response.body) body += Buffer.from(chunk).toString('utf8'); const sni = response.headers['x-sni']; + const alpn = response.headers['x-alpn']; await response.close(); console.log(JSON.stringify({ scenario, @@ -396,6 +423,7 @@ for (const scenario of scenarios) { statusCode: response.statusCode, body, sniHeader: Array.isArray(sni) ? sni[0] : sni, + alpnHeader: Array.isArray(alpn) ? alpn[0] : alpn, openSockets: openSockets() - baselineSockets, })); } catch (error) { diff --git a/packages/provision-kit/src/install-source-network-transport-proxy.test.ts b/packages/provision-kit/src/install-source-network-transport-proxy.test.ts index 8316ed5678..fdb80719a5 100644 --- a/packages/provision-kit/src/install-source-network-transport-proxy.test.ts +++ b/packages/provision-kit/src/install-source-network-transport-proxy.test.ts @@ -114,10 +114,11 @@ test('an authenticated http-scheme proxy tunnels TLS to the approved origin unde statusCode: 200, body: 'body', sniHeader: 'localhost', + alpnHeader: 'http/1.1', openSockets: 0, }, ], - `the CONNECT must carry the fixture credential, the tunnel must keep the URL host as SNI, and close must leave no socket of its own`, + `the CONNECT must carry the fixture credential, the tunnel must keep the URL host as SNI and negotiate HTTP/1.1 at the origin, and close must leave no socket of its own`, ); assert.deepEqual(lab.connectAuthoritiesSince(mark), ['127.0.0.1:']); assert.deepEqual(lab.proxyAuthorizationsSince(mark), [EXPECTED_PROXY_AUTHORIZATION]); @@ -162,6 +163,11 @@ test( assert.deepEqual(lab.proxyAuthorizationsSince(mark), [EXPECTED_PROXY_AUTHORIZATION]); await lab.settleSince(mark); assert.deepEqual(lab.proxySniSince(mark), [undefined]); + assert.deepEqual( + lab.proxyAlpnSince(mark), + ['http/1.1'], + `the proxy handshake must negotiate HTTP/1.1 offered by the transport`, + ); assert.equal(lab.liveProxySocketsSince(mark), 0); }, ); @@ -198,16 +204,22 @@ test( statusCode: 200, body: 'body', sniHeader: 'localhost', + alpnHeader: 'http/1.1', openSockets: 0, }, ], - `a named https-scheme proxy must complete the authenticated TLS origin fetch with the URL host as origin SNI and release the sockets it dialed`, + `a named https-scheme proxy must complete the authenticated TLS origin fetch with the URL host as origin SNI, must negotiate HTTP/1.1 at the origin, and must release the sockets it dialed`, ); assert.deepEqual( lab.proxySniSince(mark), ['localhost'], `the proxy handshake must present the proxy host name as SNI`, ); + assert.deepEqual( + lab.proxyAlpnSince(mark), + ['http/1.1'], + `the proxy handshake must negotiate HTTP/1.1 offered by the transport`, + ); assert.deepEqual(lab.connectAuthoritiesSince(mark), ['127.0.0.1:']); assert.deepEqual(lab.proxyAuthorizationsSince(mark), [EXPECTED_PROXY_AUTHORIZATION]); await lab.settleSince(mark); diff --git a/packages/provision-kit/src/install-source-network-transport-tls.fixtures.ts b/packages/provision-kit/src/install-source-network-transport-tls.fixtures.ts index 14eda3732d..7a3e7db053 100644 --- a/packages/provision-kit/src/install-source-network-transport-tls.fixtures.ts +++ b/packages/provision-kit/src/install-source-network-transport-tls.fixtures.ts @@ -50,6 +50,11 @@ type TlsScenarioResult = { body?: string; /** The name the TLS origin saw at the handshake, echoed back by it. `'false'` means no SNI. */ sniHeader?: string; + /** + * The protocol the TLS origin negotiated, echoed back by it. `'false'` means the handshake + * negotiated none, which is what an origin reports for a client that offers none. + */ + alpnHeader?: string; error?: { name?: string; code?: string | number; message?: string }; }; @@ -98,12 +103,14 @@ for (const scenario of scenarios) { let body = ''; for await (const chunk of response.body) body += Buffer.from(chunk).toString('utf8'); const sni = response.headers['x-sni']; + const alpn = response.headers['x-alpn']; console.log(JSON.stringify({ scenario, outcome: 'response', statusCode: response.statusCode, body, sniHeader: Array.isArray(sni) ? sni[0] : sni, + alpnHeader: Array.isArray(alpn) ? alpn[0] : alpn, })); await response.close(); } catch (error) { diff --git a/packages/provision-kit/src/install-source-network-transport.fixtures.ts b/packages/provision-kit/src/install-source-network-transport.fixtures.ts index 6141b281ea..1ccd75658d 100644 --- a/packages/provision-kit/src/install-source-network-transport.fixtures.ts +++ b/packages/provision-kit/src/install-source-network-transport.fixtures.ts @@ -126,12 +126,23 @@ export function readTlsFixturePair(root: string): { key: Buffer; cert: Buffer } }; } +/** + * The ALPN protocols the loopback TLS listeners offer. A server that advertises nothing reports + * `false` for every handshake whatever the client offered, so the origin can only evidence the + * client's offer while it advertises the protocol the transport speaks. + */ +export const FIXTURE_ALPN_PROTOCOLS = ['http/1.1']; + export function createTlsArtifactOrigin(credentials: { key: Buffer; cert: Buffer }): tls.Server { - return tls.createServer(credentials, (socket) => { + return tls.createServer({ ...credentials, ALPNProtocols: FIXTURE_ALPN_PROTOCOLS }, (socket) => { socket.on('error', () => {}); socket.once('data', () => { + // Echoes the handshake facts the client must present: the URL host as SNI, and the + // negotiated protocol, where an offer of none is reported as `false`. socket.end( - `HTTP/1.1 200 OK\r\nx-sni: ${String(socket.servername)}\r\ncontent-length: 4\r\n\r\nbody`, + `HTTP/1.1 200 OK\r\nx-sni: ${String(socket.servername)}\r\nx-alpn: ${String( + socket.alpnProtocol, + )}\r\ncontent-length: 4\r\n\r\nbody`, ); }); }); @@ -341,6 +352,7 @@ function selectedResponseHeaders( 'set-cookie', 'x-origin-host', 'x-sni', + 'x-alpn', 'location', ]) { const value = headers[name]; diff --git a/packages/provision-kit/src/install-source-network-transport.ts b/packages/provision-kit/src/install-source-network-transport.ts index c379d86184..ab5b60c4b5 100644 --- a/packages/provision-kit/src/install-source-network-transport.ts +++ b/packages/provision-kit/src/install-source-network-transport.ts @@ -4,6 +4,9 @@ import https from 'node:https'; import net, { type Socket } from 'node:net'; import tls from 'node:tls'; +/** The only application protocol this transport speaks, so it is the only one it offers at TLS. */ +const HTTP_1_1_ALPN = 'http/1.1'; + export type InstallSourceNetworkResponse = { statusCode: number; headers: Record; @@ -35,6 +38,8 @@ export async function requestApprovedUrl(params: { ? tls.connect({ ...(tunnel ? { socket: tunnel } : { host: approvedAddress, port }), ...(net.isIP(hostname) === 0 ? { servername: hostname } : {}), + // The transport speaks HTTP/1.1 on the socket, so every TLS leg must offer it. + ALPNProtocols: [HTTP_1_1_ALPN], checkServerIdentity: (_host, certificate) => tls.checkServerIdentity(hostname, certificate), }) : (tunnel ?? net.connect({ host: approvedAddress, port })); @@ -144,7 +149,9 @@ function createProxyConnectRequest(proxy: URL, authority: string): http.ClientRe path: authority, headers, agent: false, - ...(secure ? { servername: net.isIP(hostname) ? '' : hostname } : {}), + ...(secure + ? { servername: net.isIP(hostname) ? '' : hostname, ALPNProtocols: [HTTP_1_1_ALPN] } + : {}), }); } From 0296f043c883efc7451fb272df1fc10931d5c371 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sun, 22 Nov 2026 15:46:25 +0100 Subject: [PATCH 5/6] fix(provision-kit): restore SOCKS proxy support in the Node download transport #4674 replaced the Undici-backed install-source transport with a Node HTTP client that only built HTTP(S) CONNECT tunnels, so a `socks5://` or `socks://` proxy URL began failing with "Unsupported install source proxy protocol". Route both SOCKS schemes through the maintained `socks` client and hand it the approved address as its destination, so the tunnel is built for the address the resolver already vetted and the URL host is never resolved again. The proxy credentials come from the proxy URL's userinfo, matching what the previous `ProxyAgent` accepted. The transport owns the dial to the proxy, so a proxy that is down fails with the socket's own errno code, and aborting the caller signal destroys the socket mid-handshake and rejects with the caller's reason. `socks` is imported on this route only and bundled, so a download that names no SOCKS proxy never evaluates it. Add a loopback SOCKS5 lab that speaks RFC 1928 plus the RFC 1929 method and records the destination each tunnel request names, and cases that pin the approved-address destination, the artifact bytes, credential forwarding, a refused tunnel, and an abort mid-handshake. Fold the duplicated origin, socket tracking and settling of the loopback and proxy-auth labs into a shared base. --- packages/provision-kit/package.json | 3 +- ...source-network-transport-proxy.fixtures.ts | 115 ++---- ...source-network-transport-socks.fixtures.ts | 391 ++++++++++++++++++ ...all-source-network-transport-socks.test.ts | 199 +++++++++ ...stall-source-network-transport.fixtures.ts | 184 ++++++--- .../src/install-source-network-transport.ts | 85 ++++ pnpm-lock.yaml | 24 ++ tsdown.config.ts | 3 + website/docs/docs/commands.md | 2 +- 9 files changed, 861 insertions(+), 145 deletions(-) create mode 100644 packages/provision-kit/src/install-source-network-transport-socks.fixtures.ts create mode 100644 packages/provision-kit/src/install-source-network-transport-socks.test.ts diff --git a/packages/provision-kit/package.json b/packages/provision-kit/package.json index 6084b5daaa..f0424ad72c 100644 --- a/packages/provision-kit/package.json +++ b/packages/provision-kit/package.json @@ -45,6 +45,7 @@ }, "devDependencies": { "@agent-device/test-kit": "workspace:*", - "ipaddr.js": "^2.5.0" + "ipaddr.js": "^2.5.0", + "socks": "^2.8.11" } } diff --git a/packages/provision-kit/src/install-source-network-transport-proxy.fixtures.ts b/packages/provision-kit/src/install-source-network-transport-proxy.fixtures.ts index 376f832eef..06f79cceab 100644 --- a/packages/provision-kit/src/install-source-network-transport-proxy.fixtures.ts +++ b/packages/provision-kit/src/install-source-network-transport-proxy.fixtures.ts @@ -1,22 +1,21 @@ import http from 'node:http'; import https from 'node:https'; +import type { AddressInfo } from 'node:net'; import type { Duplex } from 'node:stream'; import { runTransportChild } from './install-source-network-transport-tls.fixtures.ts'; import { APPROVED_ADDRESS, APPROVED_HOSTNAME, - ARTIFACT_BODY, - authoritiesWithoutPorts, - createTlsArtifactOrigin, errorShape, FIXTURE_ALPN_PROTOCOLS, forwardConnect, - listen, readTlsFixturePair, - requestsWithoutPorts, + startLoopbackLabBase, trackSockets, type ErrorShape, + type LabMark, + type LoopbackLabBase, type ObservedRequest, type TransportSubject, } from './install-source-network-transport.fixtures.ts'; @@ -55,38 +54,23 @@ export function authHttpProxyEnvironment(proxyPort: number): NodeJS.ProcessEnv { return { http_proxy: proxy, https_proxy: proxy }; } -type ProxyAuthLabMark = { - requests: number; - connect: number; - proxyHandshakes: number; - plainProxySockets: number; - tlsProxySockets: number; -}; +/** The shared lab markers, plus the TLS-proxy handshakes only this suite counts. */ +type ProxyAuthLabMark = LabMark & { handshakes: number }; -export type ProxyAuthLab = { - originPort: number; - tlsOriginPort: number; +export type ProxyAuthLab = Omit & { /** Plain-HTTP CONNECT proxy demanding the fixture credential. */ proxyPort: number; /** TLS CONNECT proxy demanding the fixture credential, for the `https` proxy scheme. */ tlsProxyPort: number; mark(): ProxyAuthLabMark; - requestsSince(mark: ProxyAuthLabMark): ObservedRequest[]; - connectAuthoritiesSince(mark: ProxyAuthLabMark): string[]; + /** The `Proxy-Authorization` values the proxies received, after `mark`. */ proxyAuthorizationsSince(mark: ProxyAuthLabMark): (string | undefined)[]; /** The SNI names the TLS proxy accepted at its handshakes, after `mark`. */ proxySniSince(mark: ProxyAuthLabMark): (string | undefined)[]; /** The ALPN protocols the TLS proxy negotiated at its handshakes, after `mark`. */ proxyAlpnSince(mark: ProxyAuthLabMark): (string | undefined)[]; - liveProxySocketsSince(mark: ProxyAuthLabMark): number; - settleSince(mark: ProxyAuthLabMark): Promise; - dropProxySockets(): void; - close(): Promise; }; -const SETTLE_DEADLINE_MS = 700; -const SETTLE_POLL_MS = 20; - /** What the TLS proxy observed at one client handshake. */ type TlsProxyHandshake = { sni: string | undefined; @@ -115,102 +99,57 @@ function handleConnect( export async function startProxyAuthLab(root: string): Promise { const { key, cert } = readTlsFixturePair(root); - const requests: ObservedRequest[] = []; const proxyHandshakes: TlsProxyHandshake[] = []; const record = { authorities: [] as string[], authorizations: [] as (string | undefined)[] }; - const origin = http.createServer((request, response) => { - requests.push({ - method: request.method ?? '', - url: request.url ?? '', - host: request.headers.host, - }); - response.writeHead(200, { 'content-type': 'application/octet-stream' }); - response.end(ARTIFACT_BODY); - }); - const originPort = await listen(origin); - - const tlsOrigin = createTlsArtifactOrigin({ key, cert }); - const tlsOriginPort = await listen(tlsOrigin); - const proxy = http.createServer((_request, response) => { response.writeHead(501).end(); }); proxy.on('connect', (request, clientSocket, head) => handleConnect(record, request, clientSocket, head), ); - const proxySockets = trackSockets(proxy); - const proxyPort = await listen(proxy); // The same CONNECT proxy behind TLS: an `https://` proxy URL must reach this listener. It // advertises the fixture ALPN protocols, so the handshake can evidence what the client offered. - const tlsProxyServer = https.createServer( + const tlsProxy = https.createServer( { key, cert, ALPNProtocols: FIXTURE_ALPN_PROTOCOLS }, (_request, response) => { response.writeHead(501).end(); }, ); - tlsProxyServer.on('connect', (request, clientSocket, head) => + tlsProxy.on('connect', (request, clientSocket, head) => handleConnect(record, request, clientSocket, head), ); - tlsProxyServer.on('tlsClientError', () => {}); + tlsProxy.on('tlsClientError', () => {}); // Records what each client presented at the handshake, so a case can prove the proxy dial offered // the proxy host as SNI and offered the transport's application protocol. A handshake without SNI // or without a negotiated protocol records `undefined`. - tlsProxyServer.on('secureConnection', (socket) => + tlsProxy.on('secureConnection', (socket) => proxyHandshakes.push({ sni: typeof socket.servername === 'string' ? socket.servername : undefined, alpn: typeof socket.alpnProtocol === 'string' ? socket.alpnProtocol : undefined, }), ); - const tlsProxySockets = trackSockets(tlsProxyServer); - const tlsProxyPort = await listen(tlsProxyServer); + + const base = await startLoopbackLabBase({ + root, + proxies: () => [ + { server: proxy, sockets: trackSockets(proxy) }, + { server: tlsProxy, sockets: trackSockets(tlsProxy) }, + ], + connectAuthorities: () => record.authorities, + }); return { - originPort, - tlsOriginPort, - proxyPort, - tlsProxyPort, - mark: () => ({ - requests: requests.length, - connect: record.authorities.length, - proxyHandshakes: proxyHandshakes.length, - plainProxySockets: proxySockets.highestId(), - tlsProxySockets: tlsProxySockets.highestId(), - }), - requestsSince: (mark) => requestsWithoutPorts(requests.slice(mark.requests)), - connectAuthoritiesSince: (mark) => - authoritiesWithoutPorts(record.authorities.slice(mark.connect)), + ...base, + proxyPort: (proxy.address() as AddressInfo).port, + tlsProxyPort: (tlsProxy.address() as AddressInfo).port, + mark: () => ({ ...base.mark(), handshakes: proxyHandshakes.length }), proxyAuthorizationsSince: (mark) => record.authorizations.slice(mark.connect), proxySniSince: (mark) => - proxyHandshakes.slice(mark.proxyHandshakes).map((handshake) => handshake.sni), + proxyHandshakes.slice(mark.handshakes).map((handshake) => handshake.sni), proxyAlpnSince: (mark) => - proxyHandshakes.slice(mark.proxyHandshakes).map((handshake) => handshake.alpn), - liveProxySocketsSince: (mark) => - proxySockets.liveSince(mark.plainProxySockets) + - tlsProxySockets.liveSince(mark.tlsProxySockets), - settleSince: async (mark) => { - const deadline = Date.now() + SETTLE_DEADLINE_MS; - while ( - Date.now() < deadline && - (proxySockets.liveSince(mark.plainProxySockets) > 0 || - tlsProxySockets.liveSince(mark.tlsProxySockets) > 0) - ) { - await new Promise((resolve) => setTimeout(resolve, SETTLE_POLL_MS)); - } - }, - dropProxySockets: () => { - proxySockets.destroyAll(); - tlsProxySockets.destroyAll(); - }, - close: async () => { - for (const server of [origin, tlsOrigin, proxy, tlsProxyServer]) { - (server as http.Server).closeAllConnections?.(); - server.close(); - } - proxySockets.destroyAll(); - tlsProxySockets.destroyAll(); - }, + proxyHandshakes.slice(mark.handshakes).map((handshake) => handshake.alpn), }; } diff --git a/packages/provision-kit/src/install-source-network-transport-socks.fixtures.ts b/packages/provision-kit/src/install-source-network-transport-socks.fixtures.ts new file mode 100644 index 0000000000..80260c38f3 --- /dev/null +++ b/packages/provision-kit/src/install-source-network-transport-socks.fixtures.ts @@ -0,0 +1,391 @@ +import net from 'node:net'; +import type { AddressInfo } from 'node:net'; + +import { + runTransportChild, + transportModulePath, +} from './install-source-network-transport-tls.fixtures.ts'; +import { + APPROVED_ADDRESS, + startLoopbackLabBase, + trackSockets, + type ErrorShape, + type LabMark, + type LoopbackLabBase, + type ProxyFixture, +} from './install-source-network-transport.fixtures.ts'; + +/** + * Loopback-only SOCKS5 lab for the install-source transport's SOCKS proxy route (#4674 evidence). + * + * The proxies speak RFC 1928, with the RFC 1929 username/password method, over raw sockets bound to + * 127.0.0.1, and record the destination each tunnel request names — which is how a case proves the + * transport asked for the approved address rather than the URL host. The origin, TLS origin, proxy + * socket tracking and settling come from the shared loopback lab base. + */ + +/** Synthetic fixture-only SOCKS credential. Not a real credential; only this lab accepts it. */ +const SOCKS_FIXTURE_USER = 'fixture-only-user'; +/** Synthetic fixture-only SOCKS credential. Not a real credential; only this lab accepts it. */ +const SOCKS_FIXTURE_PASSWORD = 'fixture-only-secret'; + +/** What one SOCKS tunnel request named, and how the client authenticated. */ +export type SocksTunnelRequest = { + destination: string; + authMethod: 'none' | 'username-password'; +}; + +/** + * How one SOCKS proxy answers a client: `none` accepts a no-auth handshake, `required` demands the + * fixture username/password method, `silent` takes the greeting and never replies, and `refused` + * rejects the tunnel request. + */ +type SocksProxyMode = 'none' | 'required' | 'silent' | 'refused'; + +/** The shared lab markers, plus the SOCKS greetings only this suite counts. */ +export type SocksLabMark = LabMark & { greetings: number }; + +export type SocksLab = Omit & { + /** SOCKS proxy that grants a no-auth handshake. */ + socksPort: number; + /** SOCKS proxy that accepts the TCP connection and never answers the handshake. */ + silentSocksPort: number; + /** SOCKS proxy that rejects every tunnel request after the handshake. */ + refusedSocksPort: number; + /** SOCKS proxy that demands the fixture username/password method. */ + authSocksPort: number; + /** The proxy URL handed to the transport through the proxy environment variables. */ + socksProxyUrl(scheme: 'socks5' | 'socks', port: number, authenticated?: boolean): string; + mark(): SocksLabMark; + /** SOCKS greetings any of this lab's proxies received after `mark`. */ + greetingsSince(mark: SocksLabMark): number; + /** How each tunnel request granted after `mark` authenticated itself. */ + tunnelAuthMethodsSince(mark: SocksLabMark): SocksTunnelRequest['authMethod'][]; +}; + +const SOCKS_VERSION = 0x05; +const SOCKS_AUTH_NONE = 0x00; +const SOCKS_AUTH_USERNAME_PASSWORD = 0x02; +const SOCKS_AUTH_NO_ACCEPTABLE_METHODS = 0xff; +const SOCKS_REPLY_OK = 0x00; +const SOCKS_REPLY_CONNECTION_NOT_ALLOWED = 0x02; +const SOCKS_ADDRESS_IPV4 = 0x01; +const SOCKS_ADDRESS_DOMAIN = 0x03; +const SOCKS_ADDRESS_IPV6 = 0x04; +/** The reply a SOCKS5 username/password subnegotiation sends: revision 1 plus a status byte. */ +const SOCKS_SUBNEGOTIATION_REVISION = 0x01; +const SOCKS_SUBNEGOTIATION_OK = 0x00; +const SOCKS_SUBNEGOTIATION_FAILED = 0x01; + +export async function startSocksLab(root: string): Promise { + const requests: SocksTunnelRequest[] = []; + let greetings = 0; + const createProxy = (mode: SocksProxyMode): ProxyFixture => + createSocksProxyFixture({ + mode, + requests, + onGreeting: () => { + greetings += 1; + }, + }); + + const socks = createProxy('none'); + const silentSocks = createProxy('silent'); + const refusedSocks = createProxy('refused'); + const authSocks = createProxy('required'); + const proxies = [socks, silentSocks, refusedSocks, authSocks]; + + const base = await startLoopbackLabBase({ + root, + proxies: () => proxies, + connectAuthorities: () => requests.map((request) => request.destination), + }); + + return { + ...base, + socksPort: portOf(socks), + silentSocksPort: portOf(silentSocks), + refusedSocksPort: portOf(refusedSocks), + authSocksPort: portOf(authSocks), + socksProxyUrl: (scheme, port, authenticated = false) => + `${scheme}://${ + authenticated ? `${SOCKS_FIXTURE_USER}:${SOCKS_FIXTURE_PASSWORD}@` : '' + }${APPROVED_ADDRESS}:${port}`, + mark: () => ({ ...base.mark(), greetings }), + greetingsSince: (mark) => greetings - mark.greetings, + tunnelAuthMethodsSince: (mark) => + requests.slice(mark.connect).map((request) => request.authMethod), + }; +} + +function portOf(proxy: ProxyFixture): number { + return (proxy.server.address() as AddressInfo).port; +} + +export type SocksTlsScenario = 'socks5-tls-origin' | 'socks-tls-origin'; + +export type SocksTlsScenarioResult = { + scenario: SocksTlsScenario; + outcome: 'response' | 'rejection'; + statusCode?: number; + body?: string; + /** The name the TLS origin saw at the handshake, echoed back by it. `'false'` means no SNI. */ + sniHeader?: string; + /** + * The protocol the TLS origin negotiated, echoed back by it. `'false'` means the handshake + * negotiated none, which is what an origin reports for a client that offers none. + */ + alpnHeader?: string; + error?: ErrorShape; + /** + * Child TCP resources remaining above the initial process count, so a case can prove the SOCKS + * dial released the sockets it opened. + */ + openSockets: number; +}; + +/** + * Runs the SOCKS-scheme scenarios that reach the TLS origin in a fresh process: the origin's + * loopback fixture certificate can only be trusted at spawn time through `NODE_EXTRA_CA_CERTS`. The + * child owns no listeners, so the parent's lab stays the single place that records tunnel + * destinations, and the origin's echoed handshake facts are how the dial is verified. + */ +export async function runSocksTlsScenarios(params: { + /** Absolute path of the transport module the child imports. */ + here: string; + tlsOriginPort: number; + socksPort: number; + scenarios: SocksTlsScenario[]; + fixtureCertificatePath: string; +}): Promise { + return await runTransportChild( + socksTlsChildSource(), + [ + transportModulePath(params.here), + String(params.tlsOriginPort), + String(params.socksPort), + ...params.scenarios, + ], + params.fixtureCertificatePath, + Math.max(1, params.scenarios.length) * 6_000, + ); +} + +/** + * The child's source. Plain ESM so the child needs no loader beyond type stripping: it imports the + * transport module by absolute path. Arguments: transport module, the TLS origin port, the SOCKS + * proxy port, then the scenarios to run, whose name supplies the proxy scheme. + */ +function socksTlsChildSource(): string { + return ` +import { pathToFileURL } from 'node:url'; + +const [subjectPath, tlsOriginPort, socksPort, ...scenarios] = process.argv.slice(2); +const { requestApprovedUrl } = await import(pathToFileURL(subjectPath).href); +const APPROVED_ADDRESS = '127.0.0.1'; +const shape = (error) => ({ + name: error?.name, + code: error?.code, + message: error?.message, +}); + +// Keeps the event loop alive until every scenario settles, so a socket the transport still holds is +// counted rather than hidden by an early exit. +const keepAlive = setInterval(() => {}, 250); + +// The child owns no listeners, so a TCP socket handle it still holds is one the transport did not +// release. Counted before the first request so the report is the transport's own, not the child's. +const openSockets = () => + process.getActiveResourcesInfo().filter((kind) => kind === 'TCPSocketWrap').length; +const baselineSockets = openSockets(); + +for (const scenario of scenarios) { + const scheme = scenario.split('-')[0]; + try { + const response = await requestApprovedUrl({ + url: new URL('https://localhost:' + tlsOriginPort + '/artifact.bin'), + approvedAddress: APPROVED_ADDRESS, + family: 4, + headers: {}, + signal: AbortSignal.timeout(4000), + environment: { + http_proxy: scheme + '://' + APPROVED_ADDRESS + ':' + socksPort, + https_proxy: scheme + '://' + APPROVED_ADDRESS + ':' + socksPort, + }, + }); + let body = ''; + for await (const chunk of response.body) body += Buffer.from(chunk).toString('utf8'); + const sni = response.headers['x-sni']; + const alpn = response.headers['x-alpn']; + await response.close(); + console.log(JSON.stringify({ + scenario, + outcome: 'response', + statusCode: response.statusCode, + body, + sniHeader: Array.isArray(sni) ? sni[0] : sni, + alpnHeader: Array.isArray(alpn) ? alpn[0] : alpn, + openSockets: openSockets() - baselineSockets, + })); + } catch (error) { + console.log(JSON.stringify({ + scenario, + outcome: 'rejection', + error: shape(error), + openSockets: openSockets() - baselineSockets, + })); + } +} +clearInterval(keepAlive); +process.exit(0); +`; +} + +/** One SOCKS5 proxy listener: it records its tunnel requests and can be tracked and closed. */ +function createSocksProxyFixture(params: { + mode: SocksProxyMode; + requests: SocksTunnelRequest[]; + onGreeting: () => void; +}): ProxyFixture { + const server = net.createServer((client) => { + client.on('error', () => {}); + let pending = Buffer.alloc(0); + let phase: 'greeting' | 'auth' | 'request' | 'relay' = 'greeting'; + let authMethod: SocksTunnelRequest['authMethod'] = 'none'; + const onData = (chunk: Buffer) => { + pending = Buffer.concat([pending, chunk]); + for (;;) { + const consumed = + phase === 'greeting' + ? readGreeting() + : phase === 'auth' + ? readSubnegotiation() + : phase === 'request' + ? readRequest() + : undefined; + if (consumed === undefined) return; + pending = pending.subarray(consumed); + } + }; + client.on('data', onData); + + /** The bytes consumed, or `undefined` while the fixture still waits for more. */ + function readGreeting(): number | undefined { + if (pending.length < 2) return undefined; + const methodCount = pending[1] ?? 0; + if (pending.length < 2 + methodCount) return undefined; + params.onGreeting(); + const methods = Array.from(pending.subarray(2, 2 + methodCount)); + const length = 2 + methodCount; + if (params.mode === 'silent') { + // Keeps the greeting without an answer, so a case can abort mid-handshake. + phase = 'relay'; + return undefined; + } + if (params.mode === 'required' && !methods.includes(SOCKS_AUTH_USERNAME_PASSWORD)) { + client.end(Buffer.from([SOCKS_VERSION, SOCKS_AUTH_NO_ACCEPTABLE_METHODS])); + phase = 'relay'; + return length; + } + const chosen = params.mode === 'required' ? SOCKS_AUTH_USERNAME_PASSWORD : SOCKS_AUTH_NONE; + client.write(Buffer.from([SOCKS_VERSION, chosen])); + if (chosen === SOCKS_AUTH_USERNAME_PASSWORD) { + phase = 'auth'; + } else { + phase = 'request'; + } + return length; + } + + function readSubnegotiation(): number | undefined { + if (pending.length < 3) return undefined; + const userLength = pending[1] ?? 0; + if (pending.length < 3 + userLength) return undefined; + const passwordLength = pending[2 + userLength] ?? 0; + const total = 3 + userLength + passwordLength; + if (pending.length < total) return undefined; + const user = pending.subarray(2, 2 + userLength).toString('utf8'); + const password = pending.subarray(3 + userLength, total).toString('utf8'); + if (user !== SOCKS_FIXTURE_USER || password !== SOCKS_FIXTURE_PASSWORD) { + client.end(Buffer.from([SOCKS_SUBNEGOTIATION_REVISION, SOCKS_SUBNEGOTIATION_FAILED])); + phase = 'relay'; + return total; + } + authMethod = 'username-password'; + client.write(Buffer.from([SOCKS_SUBNEGOTIATION_REVISION, SOCKS_SUBNEGOTIATION_OK])); + phase = 'request'; + return total; + } + + function readRequest(): number | undefined { + if (pending.length < 5) return undefined; + const address = readSocksRequestAddress(pending); + if (address === undefined) return undefined; + if (params.mode === 'refused') { + client.end(socksReply(SOCKS_REPLY_CONNECTION_NOT_ALLOWED)); + phase = 'relay'; + return address.offset; + } + params.requests.push({ + destination: `${address.host}:${address.port}`, + authMethod, + }); + client.write(socksReply(SOCKS_REPLY_OK)); + startRelay(address.host, address.port, address.offset); + return address.offset; + } + + function startRelay(host: string, port: number, consumed: number): void { + phase = 'relay'; + client.removeListener('data', onData); + const upstream = net.connect({ host, port }); + upstream.on('error', () => client.destroy()); + client.on('error', () => upstream.destroy()); + const rest = pending.subarray(consumed); + upstream.once('connect', () => { + if (rest.length > 0) upstream.write(rest); + client.pipe(upstream); + upstream.pipe(client); + }); + } + }); + return { server, sockets: trackSockets(server) }; +} + +function socksReply(status: number): Buffer { + return Buffer.from([SOCKS_VERSION, status, 0x00, SOCKS_ADDRESS_IPV4, 0, 0, 0, 0, 0, 0]); +} + +/** The SOCKS5 request's target address and the offset just past its port. */ +function readSocksRequestAddress( + buffer: Buffer, +): { host: string; port: number; offset: number } | undefined { + const offset = 4; + const addressType = buffer[3]; + if (addressType === SOCKS_ADDRESS_IPV4) { + if (buffer.length < offset + 6) return undefined; + return { + host: buffer.subarray(offset, offset + 4).join('.'), + port: buffer.readUInt16BE(offset + 4), + offset: offset + 6, + }; + } + if (addressType === SOCKS_ADDRESS_DOMAIN) { + const length = buffer[offset] ?? 0; + if (buffer.length < offset + 1 + length + 2) return undefined; + return { + host: buffer.subarray(offset + 1, offset + 1 + length).toString('utf8'), + port: buffer.readUInt16BE(offset + 1 + length), + offset: offset + 1 + length + 2, + }; + } + if (addressType === SOCKS_ADDRESS_IPV6) { + if (buffer.length < offset + 18) return undefined; + const groups: string[] = []; + for (let index = 0; index < 16; index += 2) { + groups.push(buffer.readUInt16BE(offset + index).toString(16)); + } + return { host: groups.join(':'), port: buffer.readUInt16BE(offset + 16), offset: offset + 18 }; + } + return undefined; +} diff --git a/packages/provision-kit/src/install-source-network-transport-socks.test.ts b/packages/provision-kit/src/install-source-network-transport-socks.test.ts new file mode 100644 index 0000000000..3250905efa --- /dev/null +++ b/packages/provision-kit/src/install-source-network-transport-socks.test.ts @@ -0,0 +1,199 @@ +import assert from 'node:assert/strict'; +import path from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { afterAll, beforeAll, test } from 'vitest'; + +import { skipWhenLoopbackUnavailable } from '@agent-device/test-kit'; + +import * as nodeTransport from './install-source-network-transport.ts'; +import { + APPROVED_HOSTNAME, + ARTIFACT_BODY, + TRANSPORT_TEST_TIMEOUT_MS, + approvedUrl, + observeRequest, + operatorAbortAfter, +} from './install-source-network-transport.fixtures.ts'; +import { + runSocksTlsScenarios, + startSocksLab, + type SocksLab, +} from './install-source-network-transport-socks.fixtures.ts'; + +/** + * Pins the SOCKS proxy route the Undici-backed transport served before #4674 replaced it: a + * `socks5://` or `socks://` proxy must tunnel to the approved address and deliver the artifact + * bytes. Each case hands the transport a URL whose host is a reserved bad name, so an origin that + * served the request proves the tunnel was built and the request carried the URL identity. + */ + +const HERE = path.dirname(fileURLToPath(import.meta.url)); +const REPO_ROOT = path.resolve(HERE, '../../..'); + +/** Loopback certificate trusted by the TLS child process; its subject names cover `localhost`. */ +const FIXTURE_CERTIFICATE = path.join( + REPO_ROOT, + 'test/integration/provider-scenarios/fixtures/localhost-cert.pem', +); + +let lab: SocksLab; + +beforeAll(async () => { + // The lab binds 127.0.0.1, so it follows the shared loopback policy: an environment that only + // optionally restricts loopback binds leaves the lab unstarted and each test skips itself, while + // one that requires loopback coverage fails here. There is no test context in a hook, so the + // skip arm is a no-op; the per-test guard reports the skip. + if (await skipWhenLoopbackUnavailable({ skip: () => {} }, 'install-source SOCKS lab')) { + return; + } + lab = await startSocksLab(REPO_ROOT); +}); + +afterAll(async () => { + await lab?.close(); +}); + +/** The same SOCKS proxy selected for both URL schemes, as an operator would set it. */ +function socksEnvironment(proxyUrl: string): NodeJS.ProcessEnv { + return { http_proxy: proxyUrl, https_proxy: proxyUrl }; +} + +function run(params: { url: URL; signal: AbortSignal; environment: NodeJS.ProcessEnv }) { + return observeRequest(nodeTransport, { lab, ...params }); +} + +test.for(['socks5', 'socks'] as const)( + 'a %s proxy tunnels to the approved address and returns the artifact bytes', + async (scheme, t) => { + if (await skipWhenLoopbackUnavailable(t)) return; + const observed = await run({ + url: new URL(`http://${APPROVED_HOSTNAME}:${lab.originPort}/app.zip`), + signal: AbortSignal.timeout(TRANSPORT_TEST_TIMEOUT_MS), + environment: socksEnvironment(lab.socksProxyUrl(scheme, lab.socksPort)), + }); + + assert.equal(observed.outcome, 'response'); + assert.equal(observed.statusCode, 200); + assert.equal(observed.body, ARTIFACT_BODY); + assert.deepEqual(observed.connectAuthorities, ['127.0.0.1:']); + assert.deepEqual(observed.originSaw, [ + { method: 'GET', url: '/app.zip', host: 'approved.invalid:' }, + ]); + assert.equal(observed.liveProxySockets, 0); + }, +); + +test('a socks proxy whose URL names credentials authenticates the handshake', async (t) => { + if (await skipWhenLoopbackUnavailable(t)) return; + // This proxy grants the tunnel only to a client that completes the username/password + // subnegotiation with the fixture credential, so a 200 with the observed method proves the + // transport forwarded the proxy URL's userinfo instead of sending an unauthenticated greeting. + const mark = lab.mark(); + const observed = await run({ + url: approvedUrl(lab.originPort), + signal: AbortSignal.timeout(TRANSPORT_TEST_TIMEOUT_MS), + environment: socksEnvironment(lab.socksProxyUrl('socks5', lab.authSocksPort, true)), + }); + + assert.equal(observed.outcome, 'response'); + assert.equal(observed.statusCode, 200); + assert.equal(observed.body, ARTIFACT_BODY); + assert.deepEqual(observed.connectAuthorities, ['127.0.0.1:']); + assert.deepEqual(lab.tunnelAuthMethodsSince(mark), ['username-password']); + assert.equal(observed.liveProxySockets, 0); +}); + +test('a socks proxy that refuses the tunnel request fails the request', async (t) => { + if (await skipWhenLoopbackUnavailable(t)) return; + const mark = lab.mark(); + const observed = await run({ + url: approvedUrl(lab.originPort), + signal: AbortSignal.timeout(TRANSPORT_TEST_TIMEOUT_MS), + environment: socksEnvironment(lab.socksProxyUrl('socks5', lab.refusedSocksPort)), + }); + + assert.equal(observed.outcome, 'rejection'); + assert.equal(lab.greetingsSince(mark), 1, 'the proxy must have received the SOCKS greeting'); + assert.deepEqual( + lab.connectAuthoritiesSince(mark), + [], + 'a refused tunnel request is not an established tunnel', + ); + assert.deepEqual(observed.originSaw ?? [], []); + assert.equal(observed.liveProxySockets, 0); +}); + +test('a refused socks proxy dial is reported as ECONNREFUSED', async (t) => { + if (await skipWhenLoopbackUnavailable(t)) return; + // Nothing listens on the port the proxy URL names, so the dial to the proxy fails before any + // handshake byte is sent: the transport must surface that as the socket error, not an error of + // its own, and must not leave an unhandled socket error behind. + const observed = await run({ + url: approvedUrl(lab.originPort), + signal: AbortSignal.timeout(TRANSPORT_TEST_TIMEOUT_MS), + environment: socksEnvironment(lab.socksProxyUrl('socks5', 1)), + }); + + assert.equal(observed.outcome, 'rejection'); + assert.equal(observed.error?.code, 'ECONNREFUSED'); + assert.deepEqual(observed.connectAuthorities, []); +}); + +test('an operator abort during the socks handshake rejects with the caller error', async (t) => { + if (await skipWhenLoopbackUnavailable(t)) return; + // This proxy receives the greeting and answers nothing, so the abort lands mid-handshake. + const mark = lab.mark(); + const observed = await run({ + url: approvedUrl(lab.originPort), + signal: operatorAbortAfter(150), + environment: socksEnvironment(lab.socksProxyUrl('socks5', lab.silentSocksPort)), + }); + + assert.equal(observed.outcome, 'rejection'); + assert.equal(observed.error?.message, 'operator stop'); + assert.equal(lab.greetingsSince(mark), 1, 'the proxy must have received the SOCKS greeting'); + assert.deepEqual(observed.connectAuthorities, []); + assert.equal(observed.liveProxySockets, 0); +}); + +test( + 'a TLS origin reached through a socks5 or socks proxy keeps the URL host as SNI and negotiates HTTP/1.1', + { timeout: 30_000 }, + async (t) => { + if (await skipWhenLoopbackUnavailable(t)) return; + // The SOCKS tunnel carries the origin TLS session, so the shared TLS origin answers with the + // handshake facts. TLS trust is fixed when a process starts, so this runs the scenarios in a + // child spawned with the loopback fixture certificate as an extra CA. + const mark = lab.mark(); + const results = await runSocksTlsScenarios({ + here: HERE, + tlsOriginPort: lab.tlsOriginPort, + socksPort: lab.socksPort, + scenarios: ['socks5-tls-origin', 'socks-tls-origin'], + fixtureCertificatePath: FIXTURE_CERTIFICATE, + }); + + assert.deepEqual(results, [ + { + scenario: 'socks5-tls-origin', + outcome: 'response', + statusCode: 200, + body: 'body', + sniHeader: 'localhost', + alpnHeader: 'http/1.1', + openSockets: 0, + }, + { + scenario: 'socks-tls-origin', + outcome: 'response', + statusCode: 200, + body: 'body', + sniHeader: 'localhost', + alpnHeader: 'http/1.1', + openSockets: 0, + }, + ]); + assert.deepEqual(lab.connectAuthoritiesSince(mark), ['127.0.0.1:', '127.0.0.1:']); + assert.deepEqual(lab.tunnelAuthMethodsSince(mark), ['none', 'none']); + }, +); diff --git a/packages/provision-kit/src/install-source-network-transport.fixtures.ts b/packages/provision-kit/src/install-source-network-transport.fixtures.ts index 1ccd75658d..818b6176cc 100644 --- a/packages/provision-kit/src/install-source-network-transport.fixtures.ts +++ b/packages/provision-kit/src/install-source-network-transport.fixtures.ts @@ -79,12 +79,27 @@ export type LoopbackLab = { close(): Promise; }; -type LabMark = { +export type LabMark = { requests: number; connect: number; - proxySockets: number; + proxySockets: number[]; }; +/** + * The lab slice `observeRequest` reads: the per-case markers, what the origin and the proxy + * recorded, and the proxy socket census. Any lab that answers these questions can be observed, so + * each lab owns only the listeners its cases need. + */ +export type ObservationLab = Pick< + LoopbackLab, + | 'mark' + | 'requestsSince' + | 'connectAuthoritiesSince' + | 'liveProxySocketsSince' + | 'settleSince' + | 'dropProxySockets' +>; + export function listen(server: net.Server): Promise { return new Promise((resolve) => { server.listen(0, APPROVED_ADDRESS, () => { @@ -159,17 +174,37 @@ export function forwardConnect(port: number, clientSocket: Duplex, head: Buffer) clientSocket.on('error', () => upstream.destroy()); } -export async function startLoopbackLab(root: string): Promise { - const { key, cert } = readTlsFixturePair(root); +/** One proxy listener of a lab: its tracked sockets and the number of proxies the lab runs. */ +export type ProxyFixture = { + server: net.Server; + sockets: TrackedSockets; +}; + +/** + * The lifecycle every loopback lab shares: the origin that serves the artifact, the TLS origin that + * echoes its handshake, the proxy listeners the cases dial, and the per-case markers, slices, + * socket census and settling over their logs. A lab supplies only the proxy listeners whose tunnel + * behavior its cases exercise. + */ +export async function startLoopbackLabBase(params: { + /** Loopback certificate fixtures live under this repository root. */ + root: string; + proxies: () => ProxyFixture[]; + /** Tunnel requests the proxies recorded, in order, as `host:port` authorities. */ + connectAuthorities: () => string[]; +}): Promise { + const { key, cert } = readTlsFixturePair(params.root); const requests: ObservedRequest[] = []; - const connectAuthorities: string[] = []; const origin = http.createServer((request, response) => { requests.push({ method: request.method ?? '', url: request.url ?? '', host: request.headers.host, - custom: request.headers['x-custom'] as string | undefined, + // Recorded only when present, so a case that names no custom header compares equal. + ...(request.headers['x-custom'] === undefined + ? {} + : { custom: request.headers['x-custom'] as string }), }); if (request.url === '/redirect') { response.writeHead(302, { location: 'http://cdn.invalid/final' }); @@ -190,12 +225,94 @@ export async function startLoopbackLab(root: string): Promise { const tlsSockets = trackSockets(tlsOrigin); const tlsOriginPort = await listen(tlsOrigin); + const proxies = params.proxies(); + for (const proxy of proxies) await listen(proxy.server); + + return { + originPort, + tlsOriginPort, + mark: () => ({ + requests: requests.length, + connect: params.connectAuthorities().length, + proxySockets: proxies.map((proxy) => proxy.sockets.highestId()), + }), + requestsSince: (mark) => requestsWithoutPorts(requests.slice(mark.requests)), + connectAuthoritiesSince: (mark) => + authoritiesWithoutPorts(params.connectAuthorities().slice(mark.connect)), + liveProxySocketsSince: (mark) => + proxies.reduce( + (live, proxy, index) => live + proxy.sockets.liveSince(mark.proxySockets[index] ?? 0), + 0, + ), + settleSince: async (mark) => { + const deadline = Date.now() + SETTLE_DEADLINE_MS; + while ( + Date.now() < deadline && + proxies.some((proxy, index) => proxy.sockets.liveSince(mark.proxySockets[index] ?? 0) > 0) + ) { + await new Promise((resolve) => setTimeout(resolve, SETTLE_POLL_MS)); + } + }, + dropProxySockets: () => { + for (const proxy of proxies) proxy.sockets.destroyAll(); + }, + close: async () => { + for (const server of [origin, tlsOrigin, ...proxies.map((proxy) => proxy.server)]) { + (server as Partial).closeAllConnections?.(); + server.close(); + } + originSockets.destroyAll(); + tlsSockets.destroyAll(); + for (const proxy of proxies) proxy.sockets.destroyAll(); + }, + }; +} + +export type LoopbackLabBase = Omit< + LoopbackLab, + 'refusalPort' | 'silentPort' | 'stallerPort' | 'stalledConnectPort' | 'proxyPort' +>; + +export async function startLoopbackLab(root: string): Promise { + const connectAuthorities: string[] = []; + const refusalPorts = new Set(); + const stalledConnectPorts = new Set(); + + const proxy = http.createServer((_request, response) => { + response.writeHead(501).end(); + }); + proxy.on('connect', (request, clientSocket, head) => { + const authority = request.url ?? ''; + connectAuthorities.push(authority); + const port = Number(authority.split(':').at(-1)); + if (stalledConnectPorts.has(port)) { + clientSocket.once('end', () => clientSocket.destroy()); + clientSocket.resume(); + return; + } + if (refusalPorts.has(port)) { + clientSocket.write('HTTP/1.1 502 Bad Gateway\r\ncontent-length: 0\r\n\r\n'); + clientSocket.end(); + return; + } + forwardConnect(port, clientSocket, head); + }); + + const base = await startLoopbackLabBase({ + root, + proxies: () => [{ server: proxy, sockets: trackSockets(proxy) }], + connectAuthorities: () => connectAuthorities, + }); + + // Reachable origin the proxy refuses for CONNECT: a working tunnel would answer 200 here, so a + // refusal that reaches it would prove the transport dialed around the proxy. const refusal = http.createServer((_request, response) => { response.writeHead(200); response.end('refused-origin-was-reached'); }); const refusalSockets = trackSockets(refusal); const refusalPort = await listen(refusal); + refusalPorts.add(refusalPort); const silent = http.createServer(() => {}); const silentSockets = trackSockets(silent); @@ -208,8 +325,6 @@ export async function startLoopbackLab(root: string): Promise { const stallerSockets = trackSockets(staller); const stallerPort = await listen(staller); - const refusedPorts = new Set([refusalPort]); - // Reachable origin used only for the stalled-CONNECT case: dialing it directly answers 200, so // a response there would prove the tunnel was built when the proxy is meant to swallow it. const stalledConnect = http.createServer((_request, response) => { @@ -218,66 +333,25 @@ export async function startLoopbackLab(root: string): Promise { }); const stalledConnectSockets = trackSockets(stalledConnect); const stalledConnectPort = await listen(stalledConnect); - const stalledConnectPorts = new Set([stalledConnectPort]); - - const proxy = http.createServer((_request, response) => { - response.writeHead(501).end(); - }); - const proxySockets = trackSockets(proxy); - proxy.on('connect', (request, clientSocket, head) => { - const authority = request.url ?? ''; - connectAuthorities.push(authority); - const port = Number(authority.split(':').at(-1)); - if (stalledConnectPorts.has(port)) { - clientSocket.once('end', () => clientSocket.destroy()); - clientSocket.resume(); - return; - } - if (refusedPorts.has(port)) { - clientSocket.write('HTTP/1.1 502 Bad Gateway\r\ncontent-length: 0\r\n\r\n'); - clientSocket.end(); - return; - } - forwardConnect(port, clientSocket, head); - }); - const proxyPort = await listen(proxy); + stalledConnectPorts.add(stalledConnectPort); return { - originPort, - tlsOriginPort, + ...base, refusalPort, silentPort, stallerPort, stalledConnectPort, - proxyPort, - mark: () => ({ - requests: requests.length, - connect: connectAuthorities.length, - proxySockets: proxySockets.highestId(), - }), - requestsSince: (mark) => requestsWithoutPorts(requests.slice(mark.requests)), - connectAuthoritiesSince: (mark) => - authoritiesWithoutPorts(connectAuthorities.slice(mark.connect)), - liveProxySocketsSince: (mark) => proxySockets.liveSince(mark.proxySockets), - settleSince: async (mark) => { - const deadline = Date.now() + SETTLE_DEADLINE_MS; - while (Date.now() < deadline && proxySockets.liveSince(mark.proxySockets) > 0) { - await new Promise((resolve) => setTimeout(resolve, SETTLE_POLL_MS)); - } - }, - dropProxySockets: () => proxySockets.destroyAll(), + proxyPort: (proxy.address() as net.AddressInfo).port, close: async () => { - for (const server of [origin, tlsOrigin, refusal, silent, staller, stalledConnect, proxy]) { + await base.close(); + for (const server of [refusal, silent, staller, stalledConnect]) { (server as http.Server).closeAllConnections?.(); server.close(); } - originSockets.destroyAll(); - tlsSockets.destroyAll(); refusalSockets.destroyAll(); silentSockets.destroyAll(); stallerSockets.destroyAll(); stalledConnectSockets.destroyAll(); - proxySockets.destroyAll(); }, }; } @@ -383,7 +457,7 @@ export async function observeRequest( headers?: Record; signal: AbortSignal; environment: NodeJS.ProcessEnv; - lab: LoopbackLab; + lab: ObservationLab; readBody?: 'none'; caseDeadlineMs?: number; }, diff --git a/packages/provision-kit/src/install-source-network-transport.ts b/packages/provision-kit/src/install-source-network-transport.ts index ab5b60c4b5..6936d68e3c 100644 --- a/packages/provision-kit/src/install-source-network-transport.ts +++ b/packages/provision-kit/src/install-source-network-transport.ts @@ -3,6 +3,7 @@ import http from 'node:http'; import https from 'node:https'; import net, { type Socket } from 'node:net'; import tls from 'node:tls'; +import type { SocksRemoteHost } from 'socks'; /** The only application protocol this transport speaks, so it is the only one it offers at TLS. */ const HTTP_1_1_ALPN = 'http/1.1'; @@ -100,10 +101,94 @@ export async function requestApprovedUrl(params: { } } +/** The SOCKS5 proxy schemes this transport dials, matching the proxy selectors that name them. */ +const SOCKS5_PROTOCOLS = new Set(['socks:', 'socks5:']); +/** The port a SOCKS proxy URL means when it names none. */ +const DEFAULT_SOCKS_PORT = 1080; +/** The SOCKS5 client's own proxy-type discriminator. */ +const SOCKS5_PROXY_TYPE = 5 as const; + async function connectThroughProxy( proxy: URL, authority: string, signal: AbortSignal, +): Promise { + if (SOCKS5_PROTOCOLS.has(proxy.protocol)) { + return await connectThroughSocks5Proxy(proxy, authority, signal); + } + return await connectThroughHttpProxy(proxy, authority, signal); +} + +/** + * Dials the tunnel through a SOCKS5 proxy. The connector receives the approved address as its + * destination, so it never resolves the URL host, and the proxy credentials come from the proxy + * URL's userinfo. The transport owns the dial to the proxy and awaits it, so a proxy that is down + * fails with the socket's own errno code; the connector then reports the handshake result, and the + * caller signal owns the deadline: aborting destroys the socket mid-handshake, and the handshake + * rejects with the caller's own reason. `socks` is loaded only on this route, so a download that + * names no SOCKS proxy never evaluates it. + */ +async function connectThroughSocks5Proxy( + proxy: URL, + authority: string, + signal: AbortSignal, +): Promise { + const { SocksClient } = await import('socks'); + const proxyHost = stripBrackets(proxy.hostname); + const proxyPort = Number(proxy.port || DEFAULT_SOCKS_PORT); + const socket = net.connect({ host: proxyHost, port: proxyPort }); + const onAbort = () => socket.destroy(); + signal.addEventListener('abort', onAbort, { once: true }); + try { + await once(socket, 'connect'); + signal.throwIfAborted(); + const established = await SocksClient.createConnection({ + command: 'connect', + proxy: { + host: proxyHost, + port: proxyPort, + type: SOCKS5_PROXY_TYPE, + ...socksProxyCredentials(proxy), + }, + destination: parseSocksDestination(authority), + existing_socket: socket, + }); + signal.throwIfAborted(); + return established.socket; + } catch (error) { + await closeSocket(socket); + signal.throwIfAborted(); + throw error; + } finally { + signal.removeEventListener('abort', onAbort); + } +} + +function socksProxyCredentials(proxy: URL): { userId?: string; password?: string } { + if (!proxy.username && !proxy.password) return {}; + return { + userId: decodeURIComponent(proxy.username), + password: decodeURIComponent(proxy.password), + }; +} + +/** Splits a tunnel authority into the SOCKS destination the transport hands the connector. */ +function parseSocksDestination(authority: string): SocksRemoteHost { + if (!authority.startsWith('[')) { + const colon = authority.lastIndexOf(':'); + return { host: authority.slice(0, colon), port: Number(authority.slice(colon + 1)) }; + } + const close = authority.indexOf(']'); + return { + host: authority.slice(1, close), + port: Number(authority.slice(close + 2)), + }; +} + +async function connectThroughHttpProxy( + proxy: URL, + authority: string, + signal: AbortSignal, ): Promise { const request = createProxyConnectRequest(proxy, authority); const onAbort = () => request.destroy(); diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 6ba27f4031..50b8a12df6 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -1144,6 +1144,9 @@ importers: ipaddr.js: specifier: ^2.5.0 version: 2.5.0 + socks: + specifier: ^2.8.11 + version: 2.8.11 packages/proxy: devDependencies: @@ -4491,6 +4494,10 @@ packages: inherits@2.0.4: resolution: {integrity: sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==} + ip-address@10.7.6: + resolution: {integrity: sha512-00LYkM6byILa9eQIx6qoaXCM40xTLd56AZ4vyaPW3YTyb49VZYPo5xsiAq4tuQ54GH4R7gVdYScJ1B7B77PuTg==} + engines: {node: '>= 12'} + ipaddr.js@2.5.0: resolution: {integrity: sha512-aq+t5NAc+cS6rZQQVWC2x98CPqGtKKTMDd4Gaodv0wShnItdKg/51djkGJ1hqH+Oy0ivDftCbSLCQob8zso01w==} engines: {node: '>= 10'} @@ -5382,10 +5389,18 @@ packages: resolution: {integrity: sha512-kUMbT1oBJCpgrnKoSr0o6wPtvRWT9W9UKvGLwfJYO2WuahZRHOpEyL1ckyMGgMWh0UdpmaoFqKKD29WTomNEGA==} engines: {node: '>=8'} + smart-buffer@4.2.0: + resolution: {integrity: sha512-94hK0Hh8rPqQl2xXc3HsaBoOXKV20MToPkcXvwbISWLEs+64sBq5kFgn2kJDHb1Pry9yrP0dxrCI9RRci7RXKg==} + engines: {node: '>= 6.0.0', npm: '>= 3.0.0'} + smol-toml@1.9.1: resolution: {integrity: sha512-j7WyPdf0CJoutMzMoPLF/bVXHtKZIT9Rb4eGeEbWw8X2t5oirjPgpL+OpaENZrILYaXqYwnVH+qgUwVbl+pUJQ==} engines: {node: '>= 18'} + socks@2.8.11: + resolution: {integrity: sha512-2H/uQ7+SNP0hK16RorTak0mWrFoqo4AnAVGSUl2dT07obgWdWt9grml+VDl1LklgUOPWM4Abo0u86Cvp8vFjYw==} + engines: {node: '>= 10.0.0', npm: '>= 3.0.0'} + source-map-js@1.2.2: resolution: {integrity: sha512-KGj/8Y43x35aZVDtt+J4mK1hoLGHULMYfSkODJNQjNDC3oW1PqPoxMwo0pLUsWM/UEGzON/NxeHywEfNXNP3Vw==} engines: {node: '>=0.10.0'} @@ -8951,6 +8966,8 @@ snapshots: inherits@2.0.4: {} + ip-address@10.7.6: {} + ipaddr.js@2.5.0: {} iron-webcrypto@1.2.1: {} @@ -10098,8 +10115,15 @@ snapshots: dependencies: unicode-emoji-modifier-base: 1.0.0 + smart-buffer@4.2.0: {} + smol-toml@1.9.1: {} + socks@2.8.11: + dependencies: + ip-address: 10.7.6 + smart-buffer: 4.2.0 + source-map-js@1.2.2: {} source-map@0.7.6: {} diff --git a/tsdown.config.ts b/tsdown.config.ts index d60b1bb7fc..7b258afdb1 100644 --- a/tsdown.config.ts +++ b/tsdown.config.ts @@ -105,12 +105,15 @@ export default defineConfig({ 'https-proxy-agent', 'ignore', 'ipaddr.js', + 'ip-address', 'jpeg-js', 'ms', 'pend', 'plist', 'pngjs', 'proxy-from-env', + 'smart-buffer', + 'socks', 'streamx', 'supports-color', 'tar-stream', diff --git a/website/docs/docs/commands.md b/website/docs/docs/commands.md index af81e92037..5732ff26a8 100644 --- a/website/docs/docs/commands.md +++ b/website/docs/docs/commands.md @@ -1730,7 +1730,7 @@ agent-device install-from-source https://example.com/builds/app.aab --platform a - Repeat `--header ` for authenticated or signed downloads. Sensitive headers are not forwarded to other origins. - For a network failure during the download, `--json` reports `COMMAND_FAILED` with the system code in `error.details.networkErrorCode` when available. A phase timeout reports `connect-timeout`, `header-timeout`, or `body-timeout` in the same field. A caller cancellation has its own error reason. - `--retain-paths` keeps the downloaded and extracted files for 15 minutes. Use `--retention-ms ` to set an integer duration from 1 to 2,147,483,647 milliseconds. -- Limits: at most five redirects, no HTTPS-to-HTTP downgrade, 2 GiB download, 4 GiB extracted, 100,000 entries, and three nested archive layers. Links and special archive entries are rejected. `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` are honored. These match the Node.js client's `installFromSource()` checks. +- Limits: at most five redirects, no HTTPS-to-HTTP downgrade, 2 GiB download, 4 GiB extracted, 100,000 entries, and three nested archive layers. Links and special archive entries are rejected. `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` are honored. A proxy URL may use the `http`, `https`, `socks5`, or `socks` scheme, with optional `user:password@` credentials. These match the Node.js client's `installFromSource()` checks. ### Install a GitHub Actions artifact From 45dc0e1d3b57628e80e195835d217995f549a9b6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sun, 22 Nov 2026 18:40:50 +0100 Subject: [PATCH 6/6] fix(provision-kit): end the socks proxy dial on caller cancellation The SOCKS route awaited `once(socket, 'connect')` without the caller signal, so a proxy whose TCP dial never completes left the connect-phase wait unsettled on abort: `socket.destroy()` without an error emits `close`, and `once` rejects only on `error`. An install-from-source through an unreachable `socks5://` or `socks://` proxy hung forever, so the connect-phase watchdog and an operator cancel never ended the command. Hand the signal to the dial's own `once`, so that await settles with the caller's reason the way the request and body awaits do, and keep a no-op error listener for the abandoned socket: `once` drops its own error listener as soon as the abort wins the race, and a late socket error after that would be unhandled. Cover the dial with a case that dials a blackholed address under a short operator cancel and asserts the caller's error and a destroyed socket. Without the signal the case reports the harness's `hung` outcome instead of a rejection. --- ...all-source-network-transport-socks.test.ts | 50 +++++++++++++++++++ ...stall-source-network-transport.fixtures.ts | 5 +- .../src/install-source-network-transport.ts | 14 ++++-- 3 files changed, 63 insertions(+), 6 deletions(-) diff --git a/packages/provision-kit/src/install-source-network-transport-socks.test.ts b/packages/provision-kit/src/install-source-network-transport-socks.test.ts index 3250905efa..07bef2c653 100644 --- a/packages/provision-kit/src/install-source-network-transport-socks.test.ts +++ b/packages/provision-kit/src/install-source-network-transport-socks.test.ts @@ -9,6 +9,8 @@ import * as nodeTransport from './install-source-network-transport.ts'; import { APPROVED_HOSTNAME, ARTIFACT_BODY, + SETTLE_DEADLINE_MS, + SETTLE_POLL_MS, TRANSPORT_TEST_TIMEOUT_MS, approvedUrl, observeRequest, @@ -139,6 +141,54 @@ test('a refused socks proxy dial is reported as ECONNREFUSED', async (t) => { assert.deepEqual(observed.connectAuthorities, []); }); +test('an operator abort while the socks proxy dial never connects rejects with the caller error', async (t) => { + if (await skipWhenLoopbackUnavailable(t)) return; + // 10.255.255.1 is private space no host on this network answers, so the dial to it neither + // connects nor errors and only the caller's signal can end the connect-phase wait. The dial is + // the one await on this route the transport cannot end through a request or a body, so the await + // itself must carry the signal, and the socket it abandons must be destroyed. + const openDialResources = () => + process + .getActiveResourcesInfo() + // A dial that has not connected holds both the socket and its connect request. + .filter((kind) => kind === 'TCPSocketWrap' || kind === 'ConnectWrap').length; + const mark = lab.mark(); + const baselineDialResources = openDialResources(); + // Node releases a destroyed socket's handle just after it reports the socket closed, so this + // settles on the same schedule as the lab's own socket census. + const settleDialResources = async () => { + const deadline = Date.now() + SETTLE_DEADLINE_MS; + let open = openDialResources(); + while (Date.now() < deadline && open > baselineDialResources) { + await new Promise((resolve) => setTimeout(resolve, SETTLE_POLL_MS)); + open = openDialResources(); + } + return open; + }; + + const observed = await run({ + url: approvedUrl(lab.originPort), + signal: operatorAbortAfter(150), + environment: socksEnvironment('socks5://10.255.255.1:1080'), + }); + + assert.equal(observed.outcome, 'rejection'); + assert.equal(observed.error?.message, 'operator stop'); + assert.equal( + lab.greetingsSince(mark), + 0, + 'a dial that reached the proxy would have sent the SOCKS greeting', + ); + assert.deepEqual(lab.connectAuthoritiesSince(mark), []); + assert.deepEqual(observed.originSaw ?? [], []); + assert.equal(observed.liveProxySockets, 0); + assert.equal( + (await settleDialResources()) - baselineDialResources, + 0, + 'the aborted dial must leave no socket open', + ); +}); + test('an operator abort during the socks handshake rejects with the caller error', async (t) => { if (await skipWhenLoopbackUnavailable(t)) return; // This proxy receives the greeting and answers nothing, so the abort lands mid-handshake. diff --git a/packages/provision-kit/src/install-source-network-transport.fixtures.ts b/packages/provision-kit/src/install-source-network-transport.fixtures.ts index 818b6176cc..cbec8c545e 100644 --- a/packages/provision-kit/src/install-source-network-transport.fixtures.ts +++ b/packages/provision-kit/src/install-source-network-transport.fixtures.ts @@ -28,8 +28,9 @@ export const APPROVED_HOSTNAME = 'approved.invalid'; export const APPROVED_ADDRESS = '127.0.0.1'; export const ARTIFACT_BODY = 'artifact'; -const SETTLE_DEADLINE_MS = 700; -const SETTLE_POLL_MS = 20; +/** How long a case waits for a resource it expects the transport to release, and how often it looks. */ +export const SETTLE_DEADLINE_MS = 700; +export const SETTLE_POLL_MS = 20; export type ObservedRequest = { method: string; diff --git a/packages/provision-kit/src/install-source-network-transport.ts b/packages/provision-kit/src/install-source-network-transport.ts index 6936d68e3c..f5772e73ef 100644 --- a/packages/provision-kit/src/install-source-network-transport.ts +++ b/packages/provision-kit/src/install-source-network-transport.ts @@ -124,9 +124,9 @@ async function connectThroughProxy( * destination, so it never resolves the URL host, and the proxy credentials come from the proxy * URL's userinfo. The transport owns the dial to the proxy and awaits it, so a proxy that is down * fails with the socket's own errno code; the connector then reports the handshake result, and the - * caller signal owns the deadline: aborting destroys the socket mid-handshake, and the handshake - * rejects with the caller's own reason. `socks` is loaded only on this route, so a download that - * names no SOCKS proxy never evaluates it. + * caller signal owns the deadline: aborting destroys the socket mid-dial or mid-handshake, and the + * await rejects with the caller's own reason. `socks` is loaded only on this route, so a download + * that names no SOCKS proxy never evaluates it. */ async function connectThroughSocks5Proxy( proxy: URL, @@ -137,10 +137,16 @@ async function connectThroughSocks5Proxy( const proxyHost = stripBrackets(proxy.hostname); const proxyPort = Number(proxy.port || DEFAULT_SOCKS_PORT); const socket = net.connect({ host: proxyHost, port: proxyPort }); + // Destroying a dial that never connected can still report a late socket error, and `once` drops + // its own error listener as soon as the abort wins the race. The dial keeps one so the abandoned + // socket cannot raise an unhandled error after its await already settled. + socket.on('error', () => {}); const onAbort = () => socket.destroy(); signal.addEventListener('abort', onAbort, { once: true }); try { - await once(socket, 'connect'); + // The dial's own await must end on the caller's signal: a destroyed socket emits `close`, not + // `error`, so without the signal the connect-phase wait would never settle. + await once(socket, 'connect', { signal }); signal.throwIfAborted(); const established = await SocksClient.createConnection({ command: 'connect',