@wirebench/engine 2.1.1

package/dist/http/auth/ntlm.js

@@ -0,0 +1,377 @@
+/**
+ * NTLM (MS-NLMP) message codec: the Type 1 (NEGOTIATE), Type 2 (CHALLENGE) and
+ * Type 3 (AUTHENTICATE) messages plus the NTLMv2/LMv2 response computation, as a
+ * pure byte-level module. The connection choreography lives in `ntlm-transport.ts`.
+ *
+ * Only NTLMv2 with extended session security is produced; no session key exchange,
+ * signing or sealing, none of which HTTP needs. No MIC is emitted (it is optional
+ * for a client that negotiates no key exchange).
+ */
+import { createHmac } from 'node:crypto';
+import { WirebenchError } from '../../errors.js';
+import { md4 } from './md4.js';
+const SIGNATURE = 'NTLMSSP\0';
+const SIGNATURE_BYTES = new Uint8Array(Buffer.from(SIGNATURE, 'ascii'));
+/** NTLM negotiate flags (MS-NLMP §2.2.2.5) this codec cares about. */
+export const NTLM_FLAGS = {
+    NEGOTIATE_UNICODE: 0x00000001,
+    NEGOTIATE_OEM: 0x00000002,
+    REQUEST_TARGET: 0x00000004,
+    NEGOTIATE_NTLM: 0x00000200,
+    NEGOTIATE_OEM_DOMAIN_SUPPLIED: 0x00001000,
+    NEGOTIATE_OEM_WORKSTATION_SUPPLIED: 0x00002000,
+    NEGOTIATE_ALWAYS_SIGN: 0x00008000,
+    NEGOTIATE_EXTENDED_SESSIONSECURITY: 0x00080000,
+    NEGOTIATE_TARGET_INFO: 0x00800000,
+    NEGOTIATE_VERSION: 0x02000000,
+    NEGOTIATE_128: 0x20000000,
+    NEGOTIATE_56: 0x80000000,
+};
+/**
+ * The flag set every Wirebench Type 1/Type 3 message carries: Unicode names, NTLM with
+ * extended session security (NTLMv2), target info, a version block, and 128/56-bit key
+ * strengths. Deliberately *without* `NEGOTIATE_SIGN`/`SEAL`/`KEY_EXCH` — HTTP carries no
+ * signed or sealed payloads, so advertising them would only invite a server to expect one.
+ */
+export const DEFAULT_NEGOTIATE_FLAGS = (NTLM_FLAGS.NEGOTIATE_UNICODE |
+    NTLM_FLAGS.REQUEST_TARGET |
+    NTLM_FLAGS.NEGOTIATE_NTLM |
+    NTLM_FLAGS.NEGOTIATE_ALWAYS_SIGN |
+    NTLM_FLAGS.NEGOTIATE_EXTENDED_SESSIONSECURITY |
+    NTLM_FLAGS.NEGOTIATE_TARGET_INFO |
+    NTLM_FLAGS.NEGOTIATE_VERSION |
+    NTLM_FLAGS.NEGOTIATE_128 |
+    NTLM_FLAGS.NEGOTIATE_56) >>>
+    0;
+/** AV pair identifiers (MS-NLMP §2.2.2.1). */
+export const AV_IDS = {
+    MsvAvEOL: 0x0000,
+    MsvAvNbComputerName: 0x0001,
+    MsvAvNbDomainName: 0x0002,
+    MsvAvDnsComputerName: 0x0003,
+    MsvAvDnsDomainName: 0x0004,
+    MsvAvTimestamp: 0x0007,
+    MsvAvFlags: 0x0006,
+};
+/**
+ * The `Version` block (MS-NLMP §2.2.2.10): Windows 6.1 build 7601, NTLMSSP revision 15.
+ * Purely cosmetic — servers log it, none of them gate on it.
+ */
+const VERSION_BLOCK = new Uint8Array([0x06, 0x01, 0xb1, 0x1d, 0x00, 0x00, 0x00, 0x0f]);
+/** 100-nanosecond intervals between the Windows FILETIME epoch (1601-01-01) and the Unix epoch. */
+const FILETIME_EPOCH_OFFSET = 11644473600000n;
+/** Converts a Unix millisecond timestamp to a Windows FILETIME (100 ns ticks since 1601). */
+export function toFileTime(unixMillis) {
+    return (BigInt(Math.floor(unixMillis)) + FILETIME_EPOCH_OFFSET) * 10000n;
+}
+function utf16le(value) {
+    return new Uint8Array(Buffer.from(value, 'utf16le'));
+}
+function oem(value) {
+    return new Uint8Array(Buffer.from(value, 'latin1'));
+}
+function concat(parts) {
+    const total = parts.reduce((sum, part) => sum + part.length, 0);
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const part of parts) {
+        out.set(part, offset);
+        offset += part.length;
+    }
+    return out;
+}
+function hmacMd5(key, data) {
+    return new Uint8Array(createHmac('md5', key).update(data).digest());
+}
+/** Reads a `(Len, MaxLen, BufferOffset)` field descriptor and returns the payload slice it points at. */
+function readField(bytes, view, at) {
+    const length = view.getUint16(at, true);
+    const offset = view.getUint32(at + 4, true);
+    if (length === 0 || offset + length > bytes.length) {
+        return new Uint8Array(0);
+    }
+    return bytes.slice(offset, offset + length);
+}
+/** Writes a `(Len, MaxLen, BufferOffset)` field descriptor at `at`. */
+function writeField(view, at, length, offset) {
+    view.setUint16(at, length, true);
+    view.setUint16(at + 2, length, true);
+    view.setUint32(at + 4, offset, true);
+}
+function hasSignature(bytes) {
+    if (bytes.length < 12)
+        return false;
+    return SIGNATURE_BYTES.every((byte, index) => bytes[index] === byte);
+}
+/**
+ * Builds a Type 1 NEGOTIATE message.
+ *
+ * @param options negotiate flags plus the optional domain/workstation to advertise
+ * @returns the raw message bytes, ready for {@link encodeNtlmAuthorization}
+ */
+export function createType1(options) {
+    const domain = options?.domain !== undefined && options.domain !== '' ? oem(options.domain.toUpperCase()) : undefined;
+    const workstation = options?.workstation !== undefined && options.workstation !== ''
+        ? oem(options.workstation.toUpperCase())
+        : undefined;
+    let flags = options?.flags ?? DEFAULT_NEGOTIATE_FLAGS;
+    if (domain !== undefined)
+        flags = (flags | NTLM_FLAGS.NEGOTIATE_OEM_DOMAIN_SUPPLIED) >>> 0;
+    if (workstation !== undefined)
+        flags = (flags | NTLM_FLAGS.NEGOTIATE_OEM_WORKSTATION_SUPPLIED) >>> 0;
+    // 8 signature + 4 type + 8 domain field + 8 workstation field + 4 flags + 8 version.
+    const headerLength = 40;
+    const payload = concat([domain ?? new Uint8Array(0), workstation ?? new Uint8Array(0)]);
+    const message = new Uint8Array(headerLength + payload.length);
+    message.set(SIGNATURE_BYTES, 0);
+    const view = new DataView(message.buffer);
+    view.setUint32(8, 1, true);
+    view.setUint32(12, flags, true);
+    writeField(view, 16, domain?.length ?? 0, headerLength);
+    writeField(view, 24, workstation?.length ?? 0, headerLength + (domain?.length ?? 0));
+    message.set(VERSION_BLOCK, 32);
+    message.set(payload, headerLength);
+    return message;
+}
+/**
+ * Parses a Type 2 CHALLENGE message.
+ *
+ * @param bytes the raw message (already base64-decoded)
+ * @throws WirebenchError (`ntlm-invalid-message`) when the signature or message type is not a Type 2 message
+ */
+export function parseType2(bytes) {
+    if (!hasSignature(bytes) || bytes.length < 32) {
+        throw new WirebenchError('ntlm-invalid-message', 'not an NTLM message');
+    }
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    if (view.getUint32(8, true) !== 2) {
+        throw new WirebenchError('ntlm-invalid-message', 'not an NTLM Type 2 message');
+    }
+    const flags = view.getUint32(20, true);
+    const targetNameBytes = readField(bytes, view, 12);
+    const targetInfo = bytes.length >= 48 ? readField(bytes, view, 40) : new Uint8Array(0);
+    const version = bytes.length >= 56 ? bytes.slice(48, 56) : undefined;
+    return {
+        flags,
+        serverChallenge: bytes.slice(24, 32),
+        targetName: Buffer.from(targetNameBytes).toString((flags & NTLM_FLAGS.NEGOTIATE_UNICODE) !== 0 ? 'utf16le' : 'latin1'),
+        targetInfo,
+        ...(version !== undefined ? { version } : {}),
+    };
+}
+/**
+ * `NTOWFv2` (MS-NLMP §3.3.2): `HMAC_MD5(MD4(UTF16LE(password)), UTF16LE(UPPER(user) + domain))`.
+ * The domain keeps its case; only the user name is upper-cased.
+ *
+ * @param username the account name
+ * @param domain the domain (empty string when there is none)
+ * @param password the plaintext password — never logged, never stored by this module
+ */
+export function ntowfv2(username, domain, password) {
+    const ntHash = md4(utf16le(password));
+    return hmacMd5(ntHash, utf16le(username.toUpperCase() + domain));
+}
+/**
+ * Builds the NTLMv2 `temp` blob: version bytes, the timestamp, the client challenge and the
+ * server's AV pairs. Exported so a verifier can rebuild the exact blob it received.
+ */
+export function ntlmv2Blob(params) {
+    const head = new Uint8Array(28);
+    const view = new DataView(head.buffer);
+    head[0] = 1; // Responserversion
+    head[1] = 1; // HiResponserversion
+    view.setBigUint64(8, params.timestamp, true);
+    head.set(params.clientChallenge, 16);
+    return concat([head, params.targetInfo, new Uint8Array(4)]);
+}
+/**
+ * `NTProofStr` (MS-NLMP §3.3.2): `HMAC_MD5(NTOWFv2, serverChallenge || temp)`.
+ *
+ * @param responseKeyNt the `NTOWFv2` for the account
+ * @param serverChallenge the 8-byte challenge from the Type 2 message
+ * @param blob the `temp` blob from {@link ntlmv2Blob}
+ */
+export function ntProofString(responseKeyNt, serverChallenge, blob) {
+    return hmacMd5(responseKeyNt, concat([serverChallenge, blob]));
+}
+/**
+ * The LMv2 response: `HMAC_MD5(NTOWFv2, serverChallenge || clientChallenge) || clientChallenge`.
+ */
+export function lmv2Response(responseKeyNt, serverChallenge, clientChallenge) {
+    return concat([hmacMd5(responseKeyNt, concat([serverChallenge, clientChallenge])), clientChallenge]);
+}
+/** Appends an `MsvAvFlags` AV pair to a target-info block whose `MsvAvEOL` terminator is replaced. */
+function withAvPairs(targetInfo, extra) {
+    // Strip the trailing EOL pair (id 0, len 0 — all 4 bytes zero) so the extra pairs land before it.
+    let end = targetInfo.length;
+    if (end >= 4 &&
+        targetInfo[end - 4] === 0 &&
+        targetInfo[end - 3] === 0 &&
+        targetInfo[end - 2] === 0 &&
+        targetInfo[end - 1] === 0) {
+        end -= 4;
+    }
+    const parts = [targetInfo.slice(0, end)];
+    for (const pair of extra) {
+        const header = new Uint8Array(4);
+        const view = new DataView(header.buffer);
+        view.setUint16(0, pair.id, true);
+        view.setUint16(2, pair.value.length, true);
+        parts.push(header, pair.value);
+    }
+    parts.push(new Uint8Array(4)); // MsvAvEOL
+    return concat(parts);
+}
+/** Reads an AV-pair block into a list of `{id, value}` entries, stopping at `MsvAvEOL`. */
+export function parseAvPairs(bytes) {
+    const pairs = [];
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    let offset = 0;
+    while (offset + 4 <= bytes.length) {
+        const id = view.getUint16(offset, true);
+        const length = view.getUint16(offset + 2, true);
+        if (id === AV_IDS.MsvAvEOL)
+            break;
+        if (offset + 4 + length > bytes.length)
+            break;
+        pairs.push({ id, value: bytes.slice(offset + 4, offset + 4 + length) });
+        offset += 4 + length;
+    }
+    return pairs;
+}
+/** Builds an AV-pair block from `{id, value}` entries, terminated with `MsvAvEOL`. */
+export function buildAvPairs(pairs) {
+    return withAvPairs(new Uint8Array(4), pairs);
+}
+/**
+ * Builds a Type 3 AUTHENTICATE message answering `params.type2`, computing the NTLMv2 and
+ * LMv2 responses. The server's target info is carried through verbatim (with an
+ * `MsvAvTimestamp` added when the server sent none, and `MsvAvFlags` = 0 to state
+ * explicitly that no MIC follows).
+ *
+ * The password is used only to derive `NTOWFv2` and never appears in the message.
+ *
+ * When the server's Type 2 did not negotiate `NEGOTIATE_UNICODE`, the domain/user/workstation
+ * are OEM- (latin1-) encoded instead of UTF-16LE, and the Type 3's own flags clear the Unicode
+ * bit and set `NEGOTIATE_OEM`, matching what the server asked for.
+ *
+ * @param params the credentials, the parsed challenge and the injectable nonce/clock
+ */
+export function createType3(params) {
+    const domain = params.domain ?? '';
+    const workstation = params.workstation ?? '';
+    const responseKeyNt = ntowfv2(params.username, domain, params.password);
+    const useUnicode = (params.type2.flags & NTLM_FLAGS.NEGOTIATE_UNICODE) !== 0;
+    const encodeName = useUnicode ? utf16le : oem;
+    const serverPairs = parseAvPairs(params.type2.targetInfo);
+    const hasTimestamp = serverPairs.some((pair) => pair.id === AV_IDS.MsvAvTimestamp);
+    const timestampBytes = new Uint8Array(8);
+    new DataView(timestampBytes.buffer).setBigUint64(0, params.timestamp, true);
+    const extra = [];
+    if (!hasTimestamp)
+        extra.push({ id: AV_IDS.MsvAvTimestamp, value: timestampBytes });
+    // MsvAvFlags = 0: no MIC is present. (Bit 0x02 would claim one, which we do not send.)
+    extra.push({ id: AV_IDS.MsvAvFlags, value: new Uint8Array(4) });
+    const targetInfo = extra.length > 0 ? withAvPairs(params.type2.targetInfo, extra) : params.type2.targetInfo;
+    const blob = ntlmv2Blob({ timestamp: params.timestamp, clientChallenge: params.clientChallenge, targetInfo });
+    const ntProofStr = ntProofString(responseKeyNt, params.type2.serverChallenge, blob);
+    const ntChallengeResponse = concat([ntProofStr, blob]);
+    const lmChallengeResponse = lmv2Response(responseKeyNt, params.type2.serverChallenge, params.clientChallenge);
+    const domainBytes = encodeName(domain);
+    const userBytes = encodeName(params.username);
+    const workstationBytes = encodeName(workstation);
+    // 8 signature + 4 type + 6 * 8 field descriptors + 4 flags + 8 version. No MIC.
+    const headerLength = 72;
+    const parts = [lmChallengeResponse, ntChallengeResponse, domainBytes, userBytes, workstationBytes];
+    const message = new Uint8Array(headerLength + parts.reduce((sum, part) => sum + part.length, 0));
+    message.set(SIGNATURE_BYTES, 0);
+    const view = new DataView(message.buffer);
+    view.setUint32(8, 3, true);
+    let offset = headerLength;
+    for (const [index, part] of parts.entries()) {
+        writeField(view, 12 + index * 8, part.length, offset);
+        message.set(part, offset);
+        offset += part.length;
+    }
+    // EncryptedRandomSessionKey: empty, since no key exchange is negotiated.
+    writeField(view, 52, 0, offset);
+    let responseFlags = DEFAULT_NEGOTIATE_FLAGS;
+    if (!useUnicode) {
+        responseFlags = (responseFlags & ~NTLM_FLAGS.NEGOTIATE_UNICODE) >>> 0;
+        responseFlags = (responseFlags | NTLM_FLAGS.NEGOTIATE_OEM) >>> 0;
+    }
+    view.setUint32(60, responseFlags, true);
+    message.set(VERSION_BLOCK, 64);
+    return { message, ntProofStr, ntChallengeResponse, lmChallengeResponse, responseKeyNt };
+}
+/**
+ * Parses a Type 3 AUTHENTICATE message. Used by the test NTLM server to verify a client's
+ * response independently of {@link createType3}.
+ *
+ * @param bytes the raw message (already base64-decoded)
+ * @throws WirebenchError (`ntlm-invalid-message`) when the signature or message type is not a Type 3 message
+ */
+export function parseType3(bytes) {
+    if (!hasSignature(bytes) || bytes.length < 64) {
+        throw new WirebenchError('ntlm-invalid-message', 'not an NTLM message');
+    }
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    if (view.getUint32(8, true) !== 3) {
+        throw new WirebenchError('ntlm-invalid-message', 'not an NTLM Type 3 message');
+    }
+    const flags = view.getUint32(60, true);
+    const decode = (field) => Buffer.from(field).toString((flags & NTLM_FLAGS.NEGOTIATE_UNICODE) !== 0 ? 'utf16le' : 'latin1');
+    return {
+        flags,
+        lmChallengeResponse: readField(bytes, view, 12),
+        ntChallengeResponse: readField(bytes, view, 20),
+        domain: decode(readField(bytes, view, 28)),
+        username: decode(readField(bytes, view, 36)),
+        workstation: decode(readField(bytes, view, 44)),
+    };
+}
+/**
+ * Formats a message as an `Authorization`/`WWW-Authenticate` value: `NTLM <base64>`.
+ * Wirebench always answers with the `NTLM` scheme, even when the server advertised
+ * `Negotiate` — every server that offers raw NTLMSSP under `Negotiate` accepts it.
+ */
+export function encodeNtlmAuthorization(message) {
+    return `NTLM ${Buffer.from(message).toString('base64')}`;
+}
+/**
+ * Extracts an NTLMSSP message from a `WWW-Authenticate` header value. Accepts both
+ * `NTLM <base64>` and `Negotiate <base64>` (only when the payload really is NTLMSSP,
+ * not a Kerberos/SPNEGO token), and tolerates several challenges in one header.
+ *
+ * @param header the raw header value, or `undefined` when the response had none
+ * @returns the decoded message bytes, or `undefined` when there is no usable NTLM challenge
+ */
+export function parseNtlmChallengeHeader(header) {
+    if (header === undefined)
+        return undefined;
+    for (const part of header.split(',')) {
+        const match = /^\s*(NTLM|Negotiate)(?:\s+([A-Za-z0-9+/=]+))?\s*$/i.exec(part);
+        const token = match?.[2];
+        if (token === undefined || token === '')
+            continue;
+        let decoded;
+        try {
+            decoded = new Uint8Array(Buffer.from(token, 'base64'));
+        }
+        catch {
+            continue;
+        }
+        if (hasSignature(decoded))
+            return decoded;
+    }
+    return undefined;
+}
+/**
+ * True when `header` offers an NTLM (or NTLMSSP-over-Negotiate) challenge at all, including
+ * the bare `WWW-Authenticate: NTLM` that starts a handshake.
+ */
+export function offersNtlm(header) {
+    if (header === undefined)
+        return false;
+    return header.split(',').some((part) => /^\s*(NTLM|Negotiate)(\s|$)/i.test(part));
+}

package/dist/http/client.d.ts

@@ -0,0 +1,73 @@
+import { ProxyAgent, type Dispatcher } from 'undici';
+import type { HttpExchange, HttpRequest, ProxyOptions, TlsOptions } from './types.js';
+/**
+ * Builds a dispatcher for the given TLS/proxy options. Callers that pass
+ * custom `tls`/`proxy` own the returned dispatcher (it is not cached) and
+ * should close it when done; callers with no options get the shared default
+ * keep-alive agent.
+ */
+export declare function createDispatcher(opts: {
+    readonly tls?: TlsOptions;
+    readonly proxy?: ProxyOptions;
+    readonly keepAlive?: boolean;
+    /** Local interface address to bind outgoing sockets to; undici's `connect.localAddress`. */
+    readonly localAddress?: string;
+    /** Offer HTTP/2 in the ALPN handshake. Off by default; see `HttpRequest.allowH2`. */
+    readonly allowH2?: boolean;
+}): Dispatcher;
+/**
+ * The `ProxyAgent` options for one proxied request.
+ *
+ * The split between `requestTls` and `proxyTls` is the whole point: undici applies the
+ * agent-level `connect` to the socket it opens *to the proxy*, never to the TLS session inside
+ * the CONNECT tunnel — so passing our TLS settings there would silently drop the user's trust
+ * anchors, client certificate and `minVersion` for every proxied HTTPS request. `requestTls`
+ * is the tunnelled origin handshake (where those belong) and `proxyTls` carries only what
+ * describes the hop to the proxy itself, i.e. the bind address.
+ *
+ * `allowH2` is stated on `requestTls` rather than left to the agent, because undici builds the
+ * tunnelled connector from `requestTls` alone and its `allowH2` *defaults to true* — so an
+ * unstated flag offered `h2` in the ALPN of every proxied HTTPS handshake, including the ones
+ * whose client only speaks HTTP/1.1. Exported for the unit test that pins exactly that; not
+ * part of the package's public API (`index.ts` does not re-export it).
+ *
+ * @param proxy the resolved proxy to dial
+ * @param opts the send's TLS options and bind address
+ * @param allowH2 whether HTTP/2 may be negotiated, on the tunnelled handshake and the agent
+ * @param extra agent-level options merged on top (connection pooling, keep-alive)
+ */
+export declare function proxyAgentOptionsFor(proxy: ProxyOptions, opts: {
+    readonly tls?: TlsOptions;
+    readonly localAddress?: string;
+}, allowH2: boolean, extra?: Record<string, unknown>): ProxyAgent.Options;
+/**
+ * Builds a dispatcher pinned to a single, non-pipelined connection per origin, using the
+ * same TLS/proxy/bind-address mapping as {@link createDispatcher}. NTLM authenticates the
+ * *connection*, not the request, so all three legs of its handshake have to travel over one
+ * socket; `connections: 1` plus keep-alive gives sequential requests exactly that. The caller
+ * owns the returned dispatcher and must close it.
+ */
+export declare function createSingleConnectionDispatcher(opts: {
+    readonly tls?: TlsOptions;
+    readonly proxy?: ProxyOptions;
+    readonly localAddress?: string;
+}): Dispatcher;
+/**
+ * Sends one HTTP request and returns the full {@link HttpExchange}, including
+ * reconstructed raw wire bytes and best-effort timings. Redirects (301/302/
+ * 303/307/308) are followed manually when `req.followRedirects` is set, so we
+ * can record the `redirects[]` trail and apply fetch's POST→GET downgrade on
+ * 301/302/303.
+ *
+ * Non-2xx responses are returned as a normal exchange, never thrown — only
+ * transport-level failures (timeout, abort, DNS, TLS, refused connection,
+ * too many redirects, invalid URL) throw {@link HttpError}.
+ *
+ * A response exceeding `req.maxSizeBytes` is *not* an error: the exchange is
+ * returned with `truncated: true` and `body` cut at the cap, per the product
+ * decision that "Max Size" (Task 30) should notify, not fail, the exchange.
+ */
+export declare function sendHttp(req: HttpRequest, options?: {
+    readonly dispatcher?: Dispatcher;
+    readonly now?: () => number;
+}): Promise<HttpExchange>;