diff --git a/packages/provision-kit/package.json b/packages/provision-kit/package.json index effccf51f1..f0424ad72c 100644 --- a/packages/provision-kit/package.json +++ b/packages/provision-kit/package.json @@ -44,7 +44,8 @@ } }, "devDependencies": { + "@agent-device/test-kit": "workspace:*", "ipaddr.js": "^2.5.0", - "undici": "7.30.1" + "socks": "^2.8.11" } } 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..d33ce551af 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(); @@ -430,3 +492,63 @@ 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 }); + } +}); + +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 ae4ecbc95f..255891687e 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, @@ -116,24 +125,54 @@ 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, + ); +} + +/** 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)) + ); +} + +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 +237,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..04da99aa41 --- /dev/null +++ b/packages/provision-kit/src/install-source-network-transport-loopback.test.ts @@ -0,0 +1,328 @@ +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, 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 and the negotiated protocol 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. 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 expectedOriginHandshake) { + assert.deepEqual( + { scenario, ...byScenario.get(scenario) }, + { + 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( + 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..06f79cceab --- /dev/null +++ b/packages/provision-kit/src/install-source-network-transport-proxy.fixtures.ts @@ -0,0 +1,380 @@ +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, + errorShape, + FIXTURE_ALPN_PROTOCOLS, + forwardConnect, + readTlsFixturePair, + startLoopbackLabBase, + trackSockets, + type ErrorShape, + type LabMark, + type LoopbackLabBase, + 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 }; +} + +/** The shared lab markers, plus the TLS-proxy handshakes only this suite counts. */ +type ProxyAuthLabMark = LabMark & { handshakes: 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; + /** 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)[]; +}; + +/** 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)[] }, + 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 proxyHandshakes: TlsProxyHandshake[] = []; + const record = { authorities: [] as string[], authorizations: [] as (string | undefined)[] }; + + const proxy = http.createServer((_request, response) => { + response.writeHead(501).end(); + }); + proxy.on('connect', (request, clientSocket, head) => + handleConnect(record, request, clientSocket, head), + ); + + // 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 tlsProxy = https.createServer( + { key, cert, ALPNProtocols: FIXTURE_ALPN_PROTOCOLS }, + (_request, response) => { + response.writeHead(501).end(); + }, + ); + tlsProxy.on('connect', (request, clientSocket, head) => + handleConnect(record, request, clientSocket, head), + ); + 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`. + tlsProxy.on('secureConnection', (socket) => + proxyHandshakes.push({ + sni: typeof socket.servername === 'string' ? socket.servername : undefined, + alpn: typeof socket.alpnProtocol === 'string' ? socket.alpnProtocol : undefined, + }), + ); + + const base = await startLoopbackLabBase({ + root, + proxies: () => [ + { server: proxy, sockets: trackSockets(proxy) }, + { server: tlsProxy, sockets: trackSockets(tlsProxy) }, + ], + connectAuthorities: () => record.authorities, + }); + + return { + ...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.handshakes).map((handshake) => handshake.sni), + proxyAlpnSince: (mark) => + proxyHandshakes.slice(mark.handshakes).map((handshake) => handshake.alpn), + }; +} + +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; + /** + * 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 + * 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']; + 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); +`; +} 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..fdb80719a5 --- /dev/null +++ b/packages/provision-kit/src/install-source-network-transport-proxy.test.ts @@ -0,0 +1,227 @@ +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', + alpnHeader: 'http/1.1', + openSockets: 0, + }, + ], + `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]); + 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.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); + }, +); + +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', + 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, 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-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..07bef2c653 --- /dev/null +++ b/packages/provision-kit/src/install-source-network-transport-socks.test.ts @@ -0,0 +1,249 @@ +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, + SETTLE_DEADLINE_MS, + SETTLE_POLL_MS, + 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 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. + 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-tls.fixtures.ts b/packages/provision-kit/src/install-source-network-transport-tls.fixtures.ts new file mode 100644 index 0000000000..7a3e7db053 --- /dev/null +++ b/packages/provision-kit/src/install-source-network-transport-tls.fixtures.ts @@ -0,0 +1,148 @@ +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; + /** + * 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 }; +}; + +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']; + 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) { + 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..cbec8c545e --- /dev/null +++ b/packages/provision-kit/src/install-source-network-transport.fixtures.ts @@ -0,0 +1,603 @@ +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'; + +/** 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; + 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; +}; + +export type LabMark = { + requests: number; + connect: 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, () => { + 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)), + }; +} + +/** + * 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, 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\nx-alpn: ${String( + socket.alpnProtocol, + )}\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()); +} + +/** 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 origin = http.createServer((request, response) => { + requests.push({ + method: request.method ?? '', + url: request.url ?? '', + host: request.headers.host, + // 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' }); + 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 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); + 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); + + // 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); + stalledConnectPorts.add(stalledConnectPort); + + return { + ...base, + refusalPort, + silentPort, + stallerPort, + stalledConnectPort, + proxyPort: (proxy.address() as net.AddressInfo).port, + close: async () => { + await base.close(); + for (const server of [refusal, silent, staller, stalledConnect]) { + (server as http.Server).closeAllConnections?.(); + server.close(); + } + refusalSockets.destroyAll(); + silentSockets.destroyAll(); + stallerSockets.destroyAll(); + stalledConnectSockets.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', + 'x-alpn', + '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: ObservationLab; + 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..f5772e73ef 100644 --- a/packages/provision-kit/src/install-source-network-transport.ts +++ b/packages/provision-kit/src/install-source-network-transport.ts @@ -1,5 +1,12 @@ -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'; +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'; export type InstallSourceNetworkResponse = { statusCode: number; @@ -16,43 +23,240 @@ 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 } : {}), + // 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 })); + 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; + } +} + +/** 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-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, + 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 }); + // 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 { + // 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', + 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(); + 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, ALPNProtocols: [HTTP_1_1_ALPN] } + : {}), + }); +} + +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 +282,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 +301,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..50b8a12df6 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -1138,12 +1138,15 @@ 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 + 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 24f802546f..5732ff26a8 100644 --- a/website/docs/docs/commands.md +++ b/website/docs/docs/commands.md @@ -1728,8 +1728,9 @@ 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. +- 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