tunnelfetch 1.0.0

package/types/tls/constants.d.ts

@@ -0,0 +1,275 @@
+export namespace RECORD_TYPE {
+    let change_cipher_spec: number;
+    let alert: number;
+    let handshake: number;
+    let application_data: number;
+}
+export namespace HANDSHAKE_TYPE {
+    let client_hello: number;
+    let server_hello: number;
+    let new_session_ticket: number;
+    let end_of_early_data: number;
+    let encrypted_extensions: number;
+    let certificate: number;
+    let server_key_exchange: number;
+    let certificate_request: number;
+    let server_hello_done: number;
+    let certificate_verify: number;
+    let client_key_exchange: number;
+    let finished: number;
+    let certificate_status: number;
+    let key_update: number;
+    let message_hash: number;
+}
+/** Legacy record-layer version. Always 0x0303 on the wire after ClientHello (RFC 8446 s5.1). */
+export const LEGACY_VERSION: 771;
+export const TLS12: 771;
+export const TLS13: 772;
+export const VERSION_NAME: {
+    768: string;
+    769: string;
+    770: string;
+    771: string;
+    772: string;
+};
+export namespace EXTENSION {
+    let server_name: number;
+    let status_request: number;
+    let supported_groups: number;
+    let ec_point_formats: number;
+    let signature_algorithms: number;
+    let alpn: number;
+    let signed_certificate_timestamp: number;
+    let extended_master_secret: number;
+    let session_ticket: number;
+    let pre_shared_key: number;
+    let early_data: number;
+    let supported_versions: number;
+    let cookie: number;
+    let psk_key_exchange_modes: number;
+    let certificate_authorities: number;
+    let signature_algorithms_cert: number;
+    let key_share: number;
+    let renegotiation_info: number;
+}
+export namespace CIPHER {
+    let TLS_AES_128_GCM_SHA256: number;
+    let TLS_AES_256_GCM_SHA384: number;
+    let TLS_CHACHA20_POLY1305_SHA256: number;
+    let TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256: number;
+    let TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256: number;
+    let TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384: number;
+    let TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384: number;
+}
+/** Reverse map for error messages. A server that picks something unlisted still gets a hex code. */
+export const CIPHER_NAME: {
+    [k: string]: string;
+};
+/** Offered in ClientHello, in preference order. */
+export const TLS13_CIPHERS: number[];
+export const TLS12_CIPHERS: number[];
+/**
+ * Per-suite parameters. `hash` drives the whole key schedule; `keyLen` the AEAD key size.
+ * @typedef {object} CipherParams
+ * @property {'SHA-256' | 'SHA-384'} hash the only hashes any negotiable suite selects
+ * @property {number} hashLen
+ * @property {number} keyLen
+ * @property {number} ivLen
+ * @property {number} tagLen
+ * @property {number} [fixedIvLen] TLS 1.2 only: the 4-byte implicit GCM salt of RFC 5288
+ * @property {'ecdsa' | 'rsa'} [sig] TLS 1.2 only: the authentication family the suite names
+ */
+/** @type {{ [suite: number]: CipherParams }} */
+export const CIPHER_PARAMS: {
+    [suite: number]: CipherParams;
+};
+export namespace GROUP {
+    let secp256r1: number;
+    let secp384r1: number;
+    let secp521r1: number;
+    let x25519: number;
+    let x448: number;
+    let ffdhe2048: number;
+}
+export const GROUP_NAME: {
+    [k: string]: string;
+};
+/**
+ * Offered in preference order. X25519 first because it is the modern default and the runtime's
+ * WebCrypto has it; secp256r1 second because RFC 8446 s9.1 makes it mandatory to implement, so
+ * offering both means no compliant server can fail to find a match.
+ */
+export const SUPPORTED_GROUPS: number[];
+/**
+ * WebCrypto parameters per group, discriminated on `kind` because X25519 sizes its shared
+ * secret in bytes while ECDH sizes it in bits.
+ * @typedef {{ kind: 'x25519', algorithm: { name: string }, publicLen: number, secretLen: number }
+ *   | { kind: 'ec', algorithm: { name: string, namedCurve: string }, publicLen: number,
+ *       secretBits: number }} GroupParams
+ */
+/**
+ * WebCrypto parameters per group. x448 and the finite-field groups are absent by design.
+ * @type {{ [group: number]: GroupParams }}
+ */
+export const GROUP_PARAMS: {
+    [group: number]: GroupParams;
+};
+export namespace SIG_SCHEME {
+    let rsa_pkcs1_sha256: number;
+    let rsa_pkcs1_sha384: number;
+    let rsa_pkcs1_sha512: number;
+    let ecdsa_secp256r1_sha256: number;
+    let ecdsa_secp384r1_sha384: number;
+    let ecdsa_secp521r1_sha512: number;
+    let rsa_pss_rsae_sha256: number;
+    let rsa_pss_rsae_sha384: number;
+    let rsa_pss_rsae_sha512: number;
+    let ed25519: number;
+    let ed448: number;
+    let rsa_pss_pss_sha256: number;
+    let rsa_pss_pss_sha384: number;
+    let rsa_pss_pss_sha512: number;
+    let rsa_pkcs1_sha1: number;
+    let ecdsa_sha1: number;
+}
+export const SIG_SCHEME_NAME: {
+    [k: string]: string;
+};
+/**
+ * Offered in signature_algorithms. SHA-1 schemes are deliberately absent: they are forbidden in
+ * TLS 1.3 handshake signatures and are not worth accepting in 1.2 either.
+ */
+export const SUPPORTED_SIG_SCHEMES: number[];
+/**
+ * How to verify one signature scheme with WebCrypto. `format: 'ecdsa-der'` marks the schemes
+ * whose wire signatures need the DER-to-P1363 conversion before subtle.verify will take them.
+ * @typedef {object} SigSchemeParams
+ * @property {{ name: string, namedCurve?: string, hash?: string }} import importKey algorithm
+ * @property {{ name: string, hash?: string, saltLength?: number }} verify verify() algorithm
+ * @property {'ecdsa-der'} [format]
+ * @property {number} [curveOrderLen] byte width of the curve order, ECDSA only
+ */
+/**
+ * How to verify each scheme with WebCrypto. Absent entries are rejected with a named error.
+ * @type {{ [scheme: number]: SigSchemeParams }}
+ */
+export const SIG_SCHEME_PARAMS: {
+    [scheme: number]: SigSchemeParams;
+};
+export namespace ALERT_LEVEL {
+    let warning: number;
+    let fatal: number;
+}
+export const ALERT_DESC: {
+    0: string;
+    10: string;
+    20: string;
+    21: string;
+    22: string;
+    40: string;
+    41: string;
+    42: string;
+    43: string;
+    44: string;
+    45: string;
+    46: string;
+    47: string;
+    48: string;
+    49: string;
+    50: string;
+    51: string;
+    70: string;
+    71: string;
+    80: string;
+    86: string;
+    90: string;
+    109: string;
+    110: string;
+    112: string;
+    113: string;
+    115: string;
+    116: string;
+    120: string;
+};
+/** RFC 8446 s5.1: plaintext fragments are at most 2^14 bytes; ciphertext adds at most 256. */
+export const MAX_PLAINTEXT: number;
+export const MAX_CIPHERTEXT: number;
+/** The only protocol we will negotiate. Offering h2 we cannot speak would be a footgun. */
+export const ALPN_HTTP11: "http/1.1";
+/**
+ * RFC 8446 s4.1.3: a TLS 1.2 server that is really 1.3-aware signals a downgrade attempt by
+ * planting these in the last 8 bytes of ServerHello.random. A 1.3-capable client that lands on
+ * 1.2 must abort when it sees them.
+ */
+export const DOWNGRADE_SENTINEL_12: Uint8Array<ArrayBuffer>;
+export const DOWNGRADE_SENTINEL_11: Uint8Array<ArrayBuffer>;
+/** RFC 8446 s4.1.3: HelloRetryRequest is a ServerHello whose random is this fixed value. */
+export const HELLO_RETRY_REQUEST_RANDOM: Uint8Array<ArrayBuffer>;
+/**
+ * Per-suite parameters. `hash` drives the whole key schedule; `keyLen` the AEAD key size.
+ */
+export type CipherParams = {
+    /**
+     * the only hashes any negotiable suite selects
+     */
+    hash: "SHA-256" | "SHA-384";
+    hashLen: number;
+    keyLen: number;
+    ivLen: number;
+    tagLen: number;
+    /**
+     * TLS 1.2 only: the 4-byte implicit GCM salt of RFC 5288
+     */
+    fixedIvLen?: number | undefined;
+    /**
+     * TLS 1.2 only: the authentication family the suite names
+     */
+    sig?: "ecdsa" | "rsa" | undefined;
+};
+/**
+ * WebCrypto parameters per group, discriminated on `kind` because X25519 sizes its shared
+ * secret in bytes while ECDH sizes it in bits.
+ */
+export type GroupParams = {
+    kind: "x25519";
+    algorithm: {
+        name: string;
+    };
+    publicLen: number;
+    secretLen: number;
+} | {
+    kind: "ec";
+    algorithm: {
+        name: string;
+        namedCurve: string;
+    };
+    publicLen: number;
+    secretBits: number;
+};
+/**
+ * How to verify one signature scheme with WebCrypto. `format: 'ecdsa-der'` marks the schemes
+ * whose wire signatures need the DER-to-P1363 conversion before subtle.verify will take them.
+ */
+export type SigSchemeParams = {
+    /**
+     * importKey algorithm
+     */
+    import: {
+        name: string;
+        namedCurve?: string;
+        hash?: string;
+    };
+    /**
+     * verify() algorithm
+     */
+    verify: {
+        name: string;
+        hash?: string;
+        saltLength?: number;
+    };
+    format?: "ecdsa-der" | undefined;
+    /**
+     * byte width of the curve order, ECDSA only
+     */
+    curveOrderLen?: number | undefined;
+};

package/types/tls/extensions.d.ts

@@ -0,0 +1,195 @@
+/**
+ * server_name (RFC 6066). Only host_name (type 0) exists in practice.
+ * An IP literal must NOT be sent as SNI — RFC 6066 s3 forbids it, and servers that do virtual
+ * hosting will hand back an unrelated certificate if we do, which would look like an attack.
+ * @param {string} hostname
+ * @returns {Uint8Array | null} null for an IP literal, which sends no SNI at all
+ */
+export function encodeServerName(hostname: string): Uint8Array | null;
+/**
+ * status_request (RFC 6066 s8): ask the server to staple an OCSP response for its certificate.
+ *
+ * The body is a CertificateStatusRequest: status_type ocsp(1), an empty responder_id_list (we
+ * accept whatever responder the CA authorised — a client cannot usefully narrow that), and empty
+ * request_extensions (no nonce: a stapled response is produced before our hello exists, so a
+ * nonce could never be honoured and freshness comes from thisUpdate/nextUpdate instead).
+ *
+ * Offered in every hello, for both versions: it costs 9 bytes, and a server that ignores it
+ * loses nothing. How the answer arrives differs by version — TLS 1.2 echoes the extension and
+ * sends a separate CertificateStatus message (RFC 6066 s8), TLS 1.3 attaches it to the leaf's
+ * CertificateEntry (RFC 8446 s4.4.2.1) — and each driver consumes its own form.
+ * @returns {Uint8Array}
+ */
+export function encodeStatusRequest(): Uint8Array;
+/**
+ * @param {number[]} versions in preference order
+ * @returns {Uint8Array}
+ */
+export function encodeSupportedVersions(versions: number[]): Uint8Array;
+/**
+ * @param {number[]} [groups]
+ * @returns {Uint8Array}
+ */
+export function encodeSupportedGroups(groups?: number[]): Uint8Array;
+/**
+ * @param {number[]} [schemes]
+ * @returns {Uint8Array}
+ */
+export function encodeSignatureAlgorithms(schemes?: number[]): Uint8Array;
+/**
+ * key_share entries, in the same order as supported_groups.
+ * @param {Array<{ group: number, keyExchange: Uint8Array }>} shares the public halves only;
+ *   private keys never reach the encoder
+ * @returns {Uint8Array}
+ */
+export function encodeKeyShare(shares: Array<{
+    group: number;
+    keyExchange: Uint8Array;
+}>): Uint8Array;
+/**
+ * The HelloRetryRequest response carries a bare group id with no share.
+ * @param {number} group
+ * @returns {Uint8Array}
+ */
+export function encodeKeyShareHrr(group: number): Uint8Array;
+/**
+ * @param {string[]} protocols
+ * @returns {Uint8Array}
+ */
+export function encodeAlpn(protocols: string[]): Uint8Array;
+/**
+ * psk_key_exchange_modes (RFC 8446 s4.2.9), mandatory in any ClientHello that offers (or might
+ * later offer) pre_shared_key, and sent in every 1.3 hello regardless because some middleboxes
+ * reject its absence and it costs 6 bytes.
+ *
+ * Only psk_dhe_ke(1) is offered, ever. psk_ke would let a resumed connection run with no fresh
+ * (EC)DHE at all, so compromise of one ticket's PSK would decrypt every session resumed from it
+ * — the forward-secrecy property the rest of this package refuses to trade away (no RSA key
+ * transport for the same reason). A server honouring psk_dhe_ke must still send key_share, and
+ * selectServerKeyShare fails closed if it does not.
+ */
+export function encodePskKeyExchangeModes(): Uint8Array<ArrayBufferLike>;
+/**
+ * pre_shared_key for a ClientHello (RFC 8446 s4.2.11): one PskIdentity (the ticket plus its
+ * obfuscated age) and one PskBinderEntry. The binder cannot be known while the hello is being
+ * encoded — it is an HMAC over a transcript of the very hello it sits in, truncated just before
+ * the binders list — so it is emitted here as `binderLen` ZERO bytes, at the exact length the
+ * real binder will have, and the builder patches the real value in afterwards. RFC 8446
+ * s4.2.11.2 requires exactly this shape: every length field is computed as if the true binder
+ * were present, and only then is the binder derived and substituted.
+ *
+ * Exactly one identity is offered by design. The wire format allows a list, but this client
+ * only ever holds resumption PSKs and offers the newest usable ticket; a multi-PSK offer would
+ * multiply binder computations for a case that cannot arise here.
+ *
+ * @param {object} psk
+ * @param {Uint8Array} psk.identity the ticket, opaque, 1..2^16-1 bytes
+ * @param {number} psk.obfuscatedTicketAge uint32, already obfuscated per s4.2.11.1
+ * @param {number} psk.binderLen digest length of the PSK's hash
+ * @returns {Uint8Array}
+ */
+export function encodePreSharedKey({ identity, obfuscatedTicketAge, binderLen }: {
+    identity: Uint8Array;
+    obfuscatedTicketAge: number;
+    binderLen: number;
+}): Uint8Array;
+/**
+ * The number of trailing ClientHello bytes occupied by the binders list this client emits: the
+ * 2-byte list length, the 1-byte entry length, and the binder itself. This is the truncation
+ * arithmetic of RFC 8446 s4.2.11.2 — the binder transcript covers the hello up to and including
+ * the identities, i.e. everything except these bytes — kept next to the encoder above so the
+ * two cannot drift apart. pre_shared_key being the LAST extension (enforced by the builder) is
+ * what makes "trailing bytes of the message" and "the binders list" the same thing.
+ * @param {number} binderLen
+ * @returns {number}
+ */
+export function pskBinderTrailerLength(binderLen: number): number;
+/**
+ * pre_shared_key in a ServerHello is a bare uint16 selected_identity (RFC 8446 s4.2.11).
+ * @param {Uint8Array} data
+ * @returns {number}
+ */
+export function decodeServerPreSharedKey(data: Uint8Array): number;
+/** RFC 7627. Requesting extended master secret closes the triple-handshake hole in TLS 1.2. */
+export function encodeExtendedMasterSecret(): Uint8Array<ArrayBufferLike>;
+/**
+ * RFC 5746. An empty renegotiation_info says "I support secure renegotiation and have not
+ * renegotiated". We never renegotiate, but omitting this makes some TLS 1.2 servers reject us.
+ */
+export function encodeRenegotiationInfo(): Uint8Array<ArrayBufferLike>;
+/** RFC 8422 s5.1.2: uncompressed only. Compressed points are not implemented anywhere modern. */
+export function encodeEcPointFormats(): Uint8Array<ArrayBufferLike>;
+/**
+ * @param {Array<Uint8Array | null>} parts nulls tolerated so conditional extensions read cleanly
+ * @returns {Uint8Array}
+ */
+export function encodeExtensionBlock(parts: Array<Uint8Array | null>): Uint8Array;
+/**
+ * Decode an extension block into a Map. Duplicates are rejected rather than folded: a repeated
+ * extension is never legitimate and letting the last one win is how parser-differential bugs start.
+ * @param {Uint8Array} bytes the block content, its outer length prefix already consumed
+ * @param {string} where named in errors, e.g. 'ServerHello'
+ * @returns {Map<number, Uint8Array>}
+ */
+export function decodeExtensionBlock(bytes: Uint8Array, where: string): Map<number, Uint8Array>;
+/**
+ * RFC 8446 s4.2: the server may only send extensions the client offered. Anything else means we
+ * and the server disagree about the negotiation, which is not a state to continue from.
+ * @param {Map<number, Uint8Array>} received
+ * @param {Set<number>} offered extension types the ClientHello carried
+ * @param {string} where
+ * @returns {void} throws TlsError on the first unoffered extension
+ */
+export function rejectUnofferedExtensions(received: Map<number, Uint8Array>, offered: Set<number>, where: string): void;
+/**
+ * supported_versions in a ServerHello is a single uint16, not a list.
+ * @param {Uint8Array} data
+ * @returns {number}
+ */
+export function decodeSelectedVersion(data: Uint8Array): number;
+/**
+ * @param {Uint8Array} data
+ * @param {string} where
+ * @returns {{ group: number, keyExchange: Uint8Array }}
+ */
+export function decodeKeyShareEntry(data: Uint8Array, where: string): {
+    group: number;
+    keyExchange: Uint8Array;
+};
+/**
+ * HelloRetryRequest's key_share is a bare group with no key.
+ * @param {Uint8Array} data
+ * @returns {number}
+ */
+export function decodeKeyShareHrr(data: Uint8Array): number;
+/**
+ * @param {Uint8Array} data
+ * @returns {string} the single protocol the server selected (RFC 7301 s3.2)
+ */
+export function decodeAlpn(data: Uint8Array): string;
+/**
+ * @param {number} group
+ * @param {string} where
+ * @returns {import('./constants.js').GroupParams} throws TlsUnsupportedError when unimplemented
+ */
+export function requireSupportedGroup(group: number, where: string): import("./constants.js").GroupParams;
+/**
+ * @param {number} scheme
+ * @returns {string}
+ */
+export function describeSigScheme(scheme: number): string;
+/**
+ * @param {number} version
+ * @returns {string}
+ */
+export function describeVersion(version: number): string;
+/**
+ * Cheap classification, not validation: decides whether a name is legal as SNI.
+ * @param {string} host
+ * @returns {boolean}
+ */
+export function isIpLiteral(host: string): boolean;
+import { GROUP } from './constants.js';
+import { TLS12 } from './constants.js';
+import { TLS13 } from './constants.js';
+export { GROUP, TLS12, TLS13 };