Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.
TypeScript automationchromechromiume2e-testingelectronend-to-end-testingfirefoxjavascriptplaywrighttesttest-automationtestingtesting-toolswebwebkit
/**
* Copyright (c) Microsoft Corporation.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import { EventEmitter } from 'events';
import http2 from 'http2';
import net from 'net';
import stream from 'stream';
import tls from 'tls';
import { getProxyForUrl } from 'proxy-from-env';
import { SocksProxy } from '@utils/socksProxy';
import { debugLogger } from '@utils/debugLogger';
import { escapeHTML } from '@isomorphic/stringUtils';
import { generateSelfSignedCertificate } from '@utils/crypto';
import { rewriteErrorMessage } from '@utils/stackTrace';
import { createProxyAgent, createSocket } from '@utils/network';
import { verifyClientCertificates } from './browserContext';
import type * as types from './types';
import type { SocksSocketClosedPayload, SocksSocketDataPayload, SocksSocketRequestedPayload } from '@utils/socksProxy';
import type https from 'https';
import type { Progress } from './progress';
let dummyServerTlsOptions: tls.TlsOptions | undefined = undefined;
function loadDummyServerCertsIfNeeded() {
if (dummyServerTlsOptions)
return;
const { cert, key } = generateSelfSignedCertificate();
dummyServerTlsOptions = { key, cert };
}
// Client Certificates in Playwright are implemented as a SOCKS5 proxy that injects client certificates into the TLS handshake.
// We do that to avoid patching the browsers TLS stack and expose the certificates there.
// The following shows two flow diagrams, one for http:// and one for https://.
// Key Decision Point: First byte check (0x16 = TLS handshake)
// HTTP FLOW (Plain text):
// BROWSER PROXY SERVER
// │ │ │
// │ SOCKS5 Connect │ │
// │───────────────────────►│ │
// │ │ TCP Connect │
// │ │────────────────────────►│
// │ │ │
// │ HTTP Request │ │
// │───────────────────────►│ │
// │ │ Check: not 0x16 │
// │ │ → Direct pipe │
// │ │ │
// │ │ HTTP Request │
// │ │────────────────────────►│
// │ │ │
// │◄═══════════════════════│════════════════════════►│
// │ Plain HTTP │ Plain HTTP │
// HTTPS FLOW (TLS with client certificates):
// BROWSER PROXY SERVER
// │ │ │
// │ SOCKS5 Connect │ │
// │───────────────────────►│ │
// │ │ TCP Connect │
// │ │────────────────────────►│
// │ │ │
// │ TLS ClientHello │ │
// │ (with ALPN) │ │
// │───────────────────────►│ │
// │ │ Check: 0x16 = TLS │
// │ │ Parse ALPN protocols │
// │ │ Create dual TLS conns │
// │ │ │
// │ │ TLS ClientHello │
// │ │ (with client cert) │
// │ │────────────────────────►│
// │ │ │
// │ │◄───── TLS Handshake ────│
// │◄──── TLS Handshake ────│ │
// │ │ │
// │◄═══════════════════════│════════════════════════►│
// │ Encrypted Data │ Encrypted Data │
// │ (HTTP/1.1 or H2) │ (with client auth) │
class SocksProxyConnection {
private readonly socksProxy: ClientCertificatesProxy;
private readonly uid: string;
private readonly host: string;
private readonly port: number;
private _firstPackageReceived = false;
private _serverEncrypted!: net.Socket;
private _browserEncrypted: stream.Duplex;
private _brorwserDecrypted: Promise<tls.TLSSocket> | undefined;
private _serverCloseEventListener: () => void;
private _closed = false;
constructor(socksProxy: ClientCertificatesProxy, uid: string, host: string, port: number) {
this.socksProxy = socksProxy;
this.uid = uid;
this.host = host;
this.port = port;
this._serverCloseEventListener = async () => {
await this._brorwserDecrypted?.catch(() => {});
this._browserEncrypted.destroy();
};
this._browserEncrypted = new stream.Duplex({
read: () => { },
write: (data, encoding, callback) => {
this.socksProxy._socksProxy.sendSocketData({ uid: this.uid, data });
callback();
},
destroy: (error, callback) => {
if (error)
socksProxy._socksProxy.sendSocketError({ uid: this.uid, error: error.message });
else
socksProxy._socksProxy.sendSocketEnd({ uid: this.uid });
callback();
},
});
}
async connect() {
const proxyAgent = this.socksProxy._getProxyAgent(this.host, this.port);
if (proxyAgent)
this._serverEncrypted = await proxyAgent.connect(new EventEmitter() as any, { host: rewriteToLocalhostIfNeeded(this.host), port: this.port, secureEndpoint: false });
else
this._serverEncrypted = await createSocket(rewriteToLocalhostIfNeeded(this.host), this.port);
this._serverEncrypted.once('close', this._serverCloseEventListener);
this._serverEncrypted.once('error', error => this._browserEncrypted.destroy(error));
if (this._closed) {
this._serverEncrypted.destroy();
return;
}
this.socksProxy._socksProxy.socketConnected({
uid: this.uid,
host: this._serverEncrypted.localAddress!,
port: this._serverEncrypted.localPort!,
});
}
onClose() {
// Close the other end and cleanup TLS resources.
this._serverEncrypted.destroy();
this._browserEncrypted.destroy();
this._closed = true;
}
onData(data: Buffer) {
// HTTP / TLS are client-hello based protocols. This allows us to detect
// the protocol on the first package and attach appropriate listeners.
if (!this._firstPackageReceived) {
this._firstPackageReceived = true;
// 0x16 is the TLS "handshake" content type. Only intercept it when the origin has a client
// certificate; otherwise pass the connection through so the browser talks TLS to the server directly.
const secureContext = data[0] === 0x16 ? this.socksProxy.secureContextMap.get(normalizeOrigin(`https://${this.host}:${this.port}`)) : undefined;
if (secureContext)
this._establishTlsTunnel(this._browserEncrypted, data, secureContext);
else
this._establishPlaintextTunnel(this._browserEncrypted);
}
this._browserEncrypted.push(data);
}
private _establishPlaintextTunnel(browserEncrypted: stream.Duplex) {
browserEncrypted.pipe(this._serverEncrypted);
this._serverEncrypted.pipe(browserEncrypted);
}
private _establishTlsTunnel(browserEncrypted: stream.Duplex, clientHello: Buffer, secureContext: tls.SecureContext) {
const browserALPNProtocols = parseALPNFromClientHello(clientHello) || ['http/1.1'];
debugLogger.log('client-certificates', `Browser->Proxy ${this.host}:${this.port} offers ALPN ${browserALPNProtocols}`);
const rejectUnauthorized = !this.socksProxy.ignoreHTTPSErrors;
const serverDecrypted = tls.connect({
socket: this._serverEncrypted,
host: this.host,
port: this.port,
rejectUnauthorized,
ALPNProtocols: browserALPNProtocols,
servername: !net.isIP(this.host) ? this.host : undefined,
secureContext,
}, async () => {
const browserDecrypted = await this._upgradeToTLSIfNeeded(browserEncrypted, serverDecrypted.alpnProtocol);
debugLogger.log('client-certificates', `Proxy->Server ${this.host}:${this.port} chooses ALPN ${browserDecrypted.alpnProtocol}`);
browserDecrypted.pipe(serverDecrypted);
serverDecrypted.pipe(browserDecrypted);
const cleanup = (error: Error | undefined) => this._serverEncrypted.destroy(error);
browserDecrypted.once('error', cleanup);
serverDecrypted.once('error', cleanup);
browserDecrypted.once('close', cleanup);
serverDecrypted.once('close', cleanup);
if (this._closed)
serverDecrypted.destroy();
});
serverDecrypted.once('error', async (error: Error) => {
debugLogger.log('client-certificates', `error when connecting to server: ${error.message.replaceAll('\n', ' ')}`);
// Once we receive an error, we manually close the server connection.
// In case of an 'error' event on the server connection, we still need to perform the http2 handshake on the browser side.
// This is an async operation, so we need to remove the listener to prevent the socket from being closed too early.
// This means we call this._serverCloseEventListener manually.
this._serverEncrypted.removeListener('close', this._serverCloseEventListener);
this._serverEncrypted.destroy();
const browserDecrypted = await this._upgradeToTLSIfNeeded(this._browserEncrypted, serverDecrypted.alpnProtocol);
const responseBody = escapeHTML('Playwright client-certificate error: ' + error.message)
.replaceAll('\n', ' <br>');
if (browserDecrypted.alpnProtocol === 'h2') {
// This method is available only in Node.js 20+
if ('performServerHandshake' in http2) {
const session: http2.ServerHttp2Session = http2.performServerHandshake(browserDecrypted);
session.on('error', error => {
this._browserEncrypted.destroy(error);
});
session.once('stream', (stream: http2.ServerHttp2Stream) => {
const cleanup = (error?: Error) => {
session.close();
this._browserEncrypted.destroy(error);
};
stream.once('end', cleanup);
stream.once('error', cleanup);
stream.respond({
[http2.constants.HTTP2_HEADER_CONTENT_TYPE]: 'text/html',
[http2.constants.HTTP2_HEADER_STATUS]: 503,
});
stream.end(responseBody);
});
} else {
this._browserEncrypted.destroy(error);
}
} else {
browserDecrypted.end([
'HTTP/1.1 503 Internal Server Error',
'Content-Type: text/html; charset=utf-8',
'Content-Length: ' + Buffer.byteLength(responseBody),
'',
responseBody,
].join('\r\n'));
}
});
}
private async _upgradeToTLSIfNeeded(socket: stream.Duplex, alpnProtocol: string | false | null): Promise<tls.TLSSocket> {
// TLS errors can happen after secureConnect event from the server. In this case the socket is already upgraded to TLS.
this._brorwserDecrypted ??= new Promise<tls.TLSSocket>((resolve, reject) => {
const dummyServer = tls.createServer({
...dummyServerTlsOptions,
ALPNProtocols: [alpnProtocol || 'http/1.1'],
});
dummyServer.emit('connection', socket);
dummyServer.once('secureConnection', tlsSocket => {
dummyServer.close();
resolve(tlsSocket);
});
dummyServer.once('error', error => {
dummyServer.close();
reject(error);
});
});
return this._brorwserDecrypted;
}
}
export class ClientCertificatesProxy {
_socksProxy: SocksProxy;
private _connections: Map<string, SocksProxyConnection> = new Map();
ignoreHTTPSErrors: boolean | undefined;
secureContextMap: Map<string, tls.SecureContext> = new Map();
private _proxy: types.ProxySettings | undefined;
private constructor(
contextOptions: Pick<types.BrowserContextOptions, 'clientCertificates' | 'ignoreHTTPSErrors' | 'proxy'>
) {
verifyClientCertificates(contextOptions.clientCertificates);
this.ignoreHTTPSErrors = contextOptions.ignoreHTTPSErrors;
this._proxy = contextOptions.proxy;
this._initSecureContexts(contextOptions.clientCertificates);
this._socksProxy = new SocksProxy();
this._socksProxy.setPattern('*');
this._socksProxy.addListener(SocksProxy.Events.SocksRequested, async (payload: SocksSocketRequestedPayload) => {
try {
const connection = new SocksProxyConnection(this, payload.uid, payload.host, payload.port);
await connection.connect();
this._connections.set(payload.uid, connection);
} catch (error) {
debugLogger.log('client-certificates', `Failed to connect to ${payload.host}:${payload.port}: ${error.message}`);
this._socksProxy.socketFailed({ uid: payload.uid, errorCode: error.code });
}
});
this._socksProxy.addListener(SocksProxy.Events.SocksData, (payload: SocksSocketDataPayload) => {
this._connections.get(payload.uid)?.onData(payload.data);
});
this._socksProxy.addListener(SocksProxy.Events.SocksClosed, (payload: SocksSocketClosedPayload) => {
this._connections.get(payload.uid)?.onClose();
this._connections.delete(payload.uid);
});
loadDummyServerCertsIfNeeded();
}
_getProxyAgent(host: string, port: number) {
const url = new URL(`https://${net.isIPv6(host) ? `[${host}]` : host}:${port}`);
if (this._proxy)
return createProxyAgent(this._proxy, url);
const proxyFromEnv = getProxyForUrl(url.href);
if (proxyFromEnv)
return createProxyAgent({ server: proxyFromEnv });
}
_initSecureContexts(clientCertificates: types.BrowserContextOptions['clientCertificates']) {
// Step 1. Group certificates by origin.
const origin2certs = new Map<string, types.BrowserContextOptions['clientCertificates']>();
for (const cert of clientCertificates || []) {
const origin = normalizeOrigin(cert.origin);
const certs = origin2certs.get(origin) || [];
certs.push(cert);
origin2certs.set(origin, certs);
}
// Step 2. Create secure contexts for each origin.
for (const [origin, certs] of origin2certs) {
try {
this.secureContextMap.set(origin, tls.createSecureContext(convertClientCertificatesToTLSOptions(certs)));
} catch (error) {
error = rewriteOpenSSLErrorIfNeeded(error);
throw rewriteErrorMessage(error, `Failed to load client certificate: ${error.message}`);
}
}
}
public static async create(progress: Progress, contextOptions: Pick<types.BrowserContextOptions, 'clientCertificates' | 'ignoreHTTPSErrors' | 'proxy'>) {
const proxy = new ClientCertificatesProxy(contextOptions);
try {
await progress.race(proxy._socksProxy.listen(0, '127.0.0.1'));
return proxy;
} catch (error) {
await progress.race(proxy.close());
throw error;
}
}
public proxySettings(): types.ProxySettings {
return { server: `socks5://127.0.0.1:${this._socksProxy.port()}` };
}
public async close() {
await this._socksProxy.close();
}
}
function normalizeOrigin(origin: string): string {
try {
return new URL(origin).origin;
} catch (error) {
return origin;
}
}
function convertClientCertificatesToTLSOptions(
clientCertificates: types.BrowserContextOptions['clientCertificates']
): Pick<https.RequestOptions, 'pfx' | 'key' | 'cert'> | undefined {
if (!clientCertificates || !clientCertificates.length)
return;
const tlsOptions = {
pfx: [] as { buf: Buffer, passphrase?: string }[],
key: [] as { pem: Buffer, passphrase?: string }[],
cert: [] as Buffer[],
};
for (const cert of clientCertificates) {
if (cert.cert)
tlsOptions.cert.push(cert.cert);
if (cert.key)
tlsOptions.key.push({ pem: cert.key, passphrase: cert.passphrase });
if (cert.pfx)
tlsOptions.pfx.push({ buf: cert.pfx, passphrase: cert.passphrase });
}
return tlsOptions;
}
export function getMatchingTLSOptionsForOrigin(
clientCertificates: types.BrowserContextOptions['clientCertificates'],
origin: string
): Pick<https.RequestOptions, 'pfx' | 'key' | 'cert'> | undefined {
const matchingCerts = clientCertificates?.filter(c =>
normalizeOrigin(c.origin) === origin
);
return convertClientCertificatesToTLSOptions(matchingCerts);
}
function rewriteToLocalhostIfNeeded(host: string): string {
return host === 'local.playwright' ? 'localhost' : host;
}
export function rewriteOpenSSLErrorIfNeeded(error: Error): Error {
if (error.message !== 'unsupported' && (error as NodeJS.ErrnoException).code !== 'ERR_CRYPTO_UNSUPPORTED_OPERATION')
return error;
return rewriteErrorMessage(error, [
'Unsupported TLS certificate.',
'Most likely, the security algorithm of the given certificate was deprecated by OpenSSL.',
'For more details, see https://github.com/openssl/openssl/blob/master/README-PROVIDERS.md#the-legacy-provider',
'You could probably modernize the certificate by following the steps at https://github.com/nodejs/node/issues/40672#issuecomment-1243648223',
].join('\n'));
}
/**
* Parses the ALPN (Application-Layer Protocol Negotiation) extension from a TLS ClientHello.
* Based on RFC 8446 (TLS 1.3): https://datatracker.ietf.org/doc/html/rfc8446
*/
function parseALPNFromClientHello(buffer: Buffer): string[] | null {
if (buffer.length < 6)
return null;
// --- TLS Record Header (RFC 8446 §5.1) ---
// https://datatracker.ietf.org/doc/html/rfc8446#section-5.1
// TLSPlaintext.type (1 byte): 0x16 = TLS handshake
if (buffer[0] !== 0x16)
return null;
let offset = 5; // TLS record header is 5 bytes
// --- Handshake Header (RFC 8446 §4.1) ---
// HandshakeType (1 byte): 0x01 = ClientHello
// https://datatracker.ietf.org/doc/html/rfc8446#section-4
if (buffer[offset] !== 0x01)
return null;
offset += 4; // Handshake header: type (1) + length (3)
// --- ClientHello (RFC 8446 §4.1.2) ---
// https://datatracker.ietf.org/doc/html/rfc8446#section-4.1.2
// legacy_version (2 bytes) — always 0x0303 (TLS 1.2 for compatibility)
offset += 2;
// random (32 bytes)
offset += 32;
// legacy_session_id<0..32> (preceded by 1-byte length)
if (offset >= buffer.length)
return null;
const sessionIdLength = buffer[offset];
offset += 1 + sessionIdLength;
// cipher_suites<2..2^16-2> (preceded by 2-byte length)
if (offset + 2 > buffer.length)
return null;
const cipherSuitesLength = buffer.readUInt16BE(offset);
offset += 2 + cipherSuitesLength;
// legacy_compression_methods<1..2^8-1> (preceded by 1-byte length)
if (offset >= buffer.length)
return null;
const compressionMethodsLength = buffer[offset];
offset += 1 + compressionMethodsLength;
// extensions<8..2^16-1> (preceded by 2-byte length)
if (offset + 2 > buffer.length)
return null;
const extensionsLength = buffer.readUInt16BE(offset);
offset += 2;
const extensionsEnd = offset + extensionsLength;
if (extensionsEnd > buffer.length)
return null;
// --- Extensions (RFC 8446 §4.2) ---
// https://datatracker.ietf.org/doc/html/rfc8446#section-4.2
// Each extension is structured as:
// - extension_type (2 bytes)
// - extension_data length (2 bytes)
// - extension_data (variable)
while (offset + 4 <= extensionsEnd) {
const extensionType = buffer.readUInt16BE(offset);
offset += 2;
const extensionLength = buffer.readUInt16BE(offset);
offset += 2;
if (offset + extensionLength > extensionsEnd)
return null;
// ALPN extension (RFC 8446 §4.2.11): extension_type = 16
// https://datatracker.ietf.org/doc/html/rfc8446#section-4.2
if (extensionType === 16)
return parseALPNExtension(buffer.subarray(offset, offset + extensionLength));
offset += extensionLength;
}
return null; // No ALPN extension found
}
/**
* Parses the ALPN extension data from a ClientHello extension block.
*
* The ALPN structure is defined in:
* - RFC 7301 §3.1: https://datatracker.ietf.org/doc/html/rfc7301#section-3.1
*/
function parseALPNExtension(buffer: Buffer): string[] | null {
if (buffer.length < 2)
return null;
// protocol_name_list<2..2^16-1> (preceded by 2-byte length)
const listLength = buffer.readUInt16BE(0);
if (listLength !== buffer.length - 2)
return null;
const protocols: string[] = [];
let offset = 2;
while (offset < buffer.length) {
// ProtocolName<1..2^8-1> (preceded by 1-byte length)
const protocolLength = buffer[offset];
offset += 1;
if (offset + protocolLength > buffer.length)
break;
const protocol = buffer.subarray(offset, offset + protocolLength).toString('utf8');
protocols.push(protocol);
offset += protocolLength;
}
return protocols.length > 0 ? protocols : null;
}