tunnelfetch 1.0.0

package/types/tls/tickets.d.ts

@@ -0,0 +1,66 @@
+export class TicketStore {
+    /**
+     * @param {object} [opts]
+     * @param {number} [opts.maxPerKey] tickets retained per key, default 2 — the number a typical
+     *   server flight issues; older tickets are evicted first
+     * @param {() => number} [opts.now] epoch-ms source, injectable for tests
+     */
+    constructor({ maxPerKey, now }?: {
+        maxPerKey?: number | undefined;
+        now?: (() => number) | undefined;
+    });
+    /** @type {Map<string, Array<StoredTicket>>} */
+    _byKey: Map<string, Array<{
+        identity: Uint8Array;
+        psk: Uint8Array;
+        hash: import("./keyschedule.js").ScheduleHash;
+        ageAdd: number;
+        /**
+         * already clamped to the seven-day ceiling
+         */
+        lifetimeMs: number;
+        receivedAtMs: number;
+        peer: object;
+        cipherSuite: number;
+    }>>;
+    _maxPerKey: number;
+    _now: () => number;
+    /**
+     * @typedef {object} StoredTicket
+     * @property {Uint8Array} identity
+     * @property {Uint8Array} psk
+     * @property {import('./keyschedule.js').ScheduleHash} hash
+     * @property {number} ageAdd
+     * @property {number} lifetimeMs already clamped to the seven-day ceiling
+     * @property {number} receivedAtMs
+     * @property {object} peer
+     * @property {number} cipherSuite
+     */
+    /** Total tickets currently held, for tests and diagnostics. */
+    get size(): number;
+    /**
+     * Store a captured ticket under `key`. Returns whether it was retained: a zero (or negative)
+     * lifetime is a server instruction to discard immediately and is honoured silently — that is
+     * the server's prerogative, not an error — while a structurally unusable capture (no PSK, no
+     * identity, unknown hash) throws, because the only producer is this package's own driver and
+     * a malformed capture is a bug, not an input.
+     *
+     * @param {string} key the pool key of the connection the ticket arrived on
+     * @param {import('./connect.js').CapturedTicket} captured
+     * @returns {boolean}
+     */
+    put(key: string, captured: import("./connect.js").CapturedTicket): boolean;
+    /**
+     * Take the freshest usable ticket for `key` as a ready-to-offer PSK, or null. The ticket is
+     * removed either way it goes from here — single use — and expired tickets encountered on the
+     * way are dropped rather than offered: a server checks obfuscated_ticket_age against the
+     * lifetime it granted, and offering a stale ticket is a round trip spent being refused.
+     *
+     * @param {string} key MUST be built from the same inputs as the connection's pool key; this
+     *   equality is the entire trust story of resumption (see the module comment)
+     * @returns {import('./connect.js').ResumptionOffer | null}
+     */
+    take(key: string): import("./connect.js").ResumptionOffer | null;
+    /** Drop everything; a closed Client must not keep credentials alive. */
+    clear(): void;
+}

package/types/tls/transcript.d.ts

@@ -0,0 +1,52 @@
+export class Transcript {
+    /**
+     * @param {import('./keyschedule.js').ScheduleHash} hash fixed once the cipher suite is known
+     * @param {{ maxBytes?: number }} [opts] transcript buffer cap, default 1 MiB
+     */
+    constructor(hash: import("./keyschedule.js").ScheduleHash, { maxBytes }?: {
+        maxBytes?: number;
+    });
+    _hash: import("./keyschedule.js").ScheduleHash;
+    /** @type {Uint8Array[]} */
+    _chunks: Uint8Array[];
+    _len: number;
+    _maxBytes: number;
+    /** @type {Uint8Array | null} digest cache, invalidated by update() */
+    _cached: Uint8Array | null;
+    get bytesBuffered(): number;
+    /**
+     * Append raw handshake message bytes (including the 4-byte message header — the transcript
+     * is over complete Handshake structs, never record framing).
+     * @param {Uint8Array} bytes
+     */
+    update(bytes: Uint8Array): void;
+    /**
+     * Digest of everything appended so far. Does not consume; call as often as needed.
+     * @returns {Promise<Uint8Array>}
+     */
+    hash(): Promise<Uint8Array>;
+    /**
+     * Digest of everything appended so far PLUS `extra`, without appending it.
+     *
+     * Exists for exactly one caller: the PSK binder after a HelloRetryRequest, which is an HMAC
+     * over Transcript-Hash(message_hash(CH1) || HRR || Truncate(CH2)) (RFC 8446 s4.2.11.2). The
+     * truncated ClientHello2 must be hashed as a continuation of the real transcript but must
+     * never BECOME part of it — the transcript proper gets the full ClientHello2 with its binder,
+     * and folding the truncated form in even transiently would leave a window where the two
+     * bookkeepings disagree.
+     * @param {Uint8Array} extra
+     * @returns {Promise<Uint8Array>}
+     */
+    hashWith(extra: Uint8Array): Promise<Uint8Array>;
+    /**
+     * HelloRetryRequest transcript substitution (RFC 8446 s4.4.1): when a ServerHello is an HRR,
+     * the transcript restarts as a synthetic handshake message
+     *
+     *   message_hash(0xFE) || uint24 Hash.length || Hash(ClientHello1)
+     *
+     * so that a stateless server need only remember the hash of the first ClientHello. Call this
+     * after ClientHello1 is the only message in the transcript, before appending the HRR itself.
+     * @returns {Promise<void>}
+     */
+    replaceWithMessageHash(): Promise<void>;
+}

package/types/tls/wire.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Convenience: build a length-prefixed vector standalone.
+ * @param {1 | 2 | 3} lenBytes
+ * @param {Uint8Array} body
+ * @returns {Uint8Array}
+ */
+export function vector(lenBytes: 1 | 2 | 3, body: Uint8Array): Uint8Array;
+/**
+ * Encode a handshake message: 1-byte type, 3-byte length, body.
+ * @param {number} type
+ * @param {Uint8Array} body
+ * @returns {Uint8Array}
+ */
+export function handshakeMessage(type: number, body: Uint8Array): Uint8Array;
+/** Sequential reader over a byte range with hard bounds. */
+export class Cursor {
+    /**
+     * @param {Uint8Array} bytes
+     * @param {string} what named in every error so a failure says which structure was malformed
+     */
+    constructor(bytes: Uint8Array, what?: string);
+    bytes: Uint8Array<ArrayBufferLike>;
+    pos: number;
+    what: string;
+    get remaining(): number;
+    get done(): boolean;
+    /**
+     * @param {number} n
+     * @param {string} field
+     */
+    _need(n: number, field: string): void;
+    /**
+     * @param {string} [field]
+     * @returns {number}
+     */
+    u8(field?: string): number;
+    /**
+     * @param {string} [field]
+     * @returns {number}
+     */
+    u16(field?: string): number;
+    /**
+     * @param {string} [field]
+     * @returns {number}
+     */
+    u24(field?: string): number;
+    /**
+     * @param {string} [field]
+     * @returns {number}
+     */
+    u32(field?: string): number;
+    /**
+     * Fixed-length opaque bytes. Returns a view into the original buffer, never a copy.
+     * @param {number} n
+     * @param {string} [field]
+     * @returns {Uint8Array}
+     */
+    take(n: number, field?: string): Uint8Array;
+    /**
+     * A vector whose length is carried in `lenBytes` (1, 2 or 3) leading octets.
+     * @param {1 | 2 | 3} lenBytes
+     * @param {string} [field]
+     * @returns {Uint8Array}
+     */
+    vector(lenBytes: 1 | 2 | 3, field?: string): Uint8Array;
+    /**
+     * Like `vector`, but hands back a Cursor so nested structures inherit the bound.
+     * @param {1 | 2 | 3} lenBytes
+     * @param {string} [field]
+     * @returns {Cursor}
+     */
+    sub(lenBytes: 1 | 2 | 3, field?: string): Cursor;
+    /**
+     * Assert nothing is left. Trailing data inside a length-delimited structure means our idea of
+     * the structure and the peer's disagree, which is exactly when to stop rather than guess.
+     * @param {string} [field]
+     */
+    end(field?: string): void;
+}
+/** Accumulating writer. Kept dumb: correctness of lengths comes from `vector()` below. */
+export class Builder {
+    /** @type {Uint8Array[]} */
+    parts: Uint8Array[];
+    length: number;
+    /**
+     * @param {Uint8Array} bytes
+     * @returns {this}
+     */
+    push(bytes: Uint8Array): this;
+    /** @param {number} n @returns {this} */
+    u8(n: number): this;
+    /** @param {number} n @returns {this} */
+    u16(n: number): this;
+    /** @param {number} n @returns {this} */
+    u24(n: number): this;
+    /**
+     * Write `body` prefixed by its length in `lenBytes` octets. Taking the body as bytes rather
+     * than back-patching a placeholder means a length can never drift from what follows it.
+     * @param {1 | 2 | 3} lenBytes
+     * @param {Uint8Array} body
+     * @returns {this}
+     */
+    vector(lenBytes: 1 | 2 | 3, body: Uint8Array): this;
+    /** @returns {Uint8Array} */
+    build(): Uint8Array;
+}

package/types/transport.d.ts

@@ -0,0 +1,222 @@
+/**
+ * A request URL reduced to what the transport dials.
+ * @typedef {object} TransportTarget
+ * @property {URL} url
+ * @property {string} hostname IPv6 unbracketed, as the socket API and SOCKS5 want it
+ * @property {number} port explicit port, or the scheme default
+ * @property {boolean} secure whether the scheme is https:
+ */
+/**
+ * Split a request URL into what the transport needs. Throws ConfigError on any scheme other
+ * than http: and https:.
+ * @param {string | URL} input
+ * @returns {TransportTarget}
+ */
+export function targetFromUrl(input: string | URL): TransportTarget;
+/**
+ * What a Response's `tunnelfetch` detail reports about the connection, before the HTTP layer
+ * adds the per-response httpVersion and framing.
+ * @typedef {object} ConnectionInfo
+ * @property {string} url
+ * @property {boolean} proxied
+ * @property {string | null} proxy the proxy actually used, credentials omitted
+ * @property {import('./tls/connect.js').TlsSessionInfo | null} tls null for cleartext
+ */
+/**
+ * A live connection carrying application bytes: the duplex, its provenance, and the deadline
+ * controller that governs it. This is what the pool stores and what sendAndReceive consumes.
+ * @typedef {object} Connection
+ * @property {ReadableStream<Uint8Array>} readable
+ * @property {WritableStream<Uint8Array>} writable
+ * @property {() => Promise<void> | void} close
+ * @property {ConnectionInfo} info
+ * @property {import('./trust/index.js').ParsedCertificate | null} [peerCertificate] TLS only;
+ *   null when trust mode 'none' accepted a leaf it could not parse
+ * @property {DeadlineController} deadlines
+ * @property {boolean} ownsDeadlines whether this call created the controller (and must dispose
+ *   it) rather than borrowing the caller's
+ */
+/**
+ * @typedef {object} OpenConnectionOptions
+ * @property {string | URL} url
+ * @property {import('./proxy/index.js').ConnectFn} connect injected socket factory
+ * @property {string | import('./proxy/index.js').ProxyConfig | null} [proxy]
+ * @property {import('./trust/index.js').TrustConfig} [trust] the `verify=`-style knob, passed
+ *   through to the trust layer
+ * @property {DeadlineController} [deadlines] borrow the request's controller; omitting it makes
+ *   this call own (and dispose) a fresh one
+ * @property {import('./tls/connect.js').TlsOptions} [tls] handshake options
+ * @property {string[]} [alpn] the ALPN protocol list to offer, newest/most-preferred first.
+ *   Kept separate from `tls` so offering `h2` does not read as a user-supplied TLS option (which
+ *   would disable native-fetch delegation and enter the pool key). `tls.alpn` still wins if set.
+ * @property {{ offer?: import('./tls/connect.js').ResumptionOffer | null,
+ *   onTicket?: (t: import('./tls/connect.js').CapturedTicket) => void }} [resumption]
+ *   session-resumption wiring, injected per connection by the Client. Separate from `tls` for
+ *   the same reason `alpn` is: it must neither disable native-fetch delegation nor enter the
+ *   pool key — it is not caller configuration, it is state the Client derived FROM the pool key.
+ * @property {import('./tls/connect.js').TlsDeps} [deps] injectable randomness/keygen for
+ *   reproducible handshakes
+ * @property {AbortSignal} [signal]
+ * @property {{ maxProxyReplyBytes?: number }} [limits] cap on the proxy CONNECT reply head
+ * @property {number} [now] epoch ms override for certificate validity
+ */
+/**
+ * Open a connection carrying application bytes for `url`. Throws (ProxyError, TlsError,
+ * CertificateError, TimeoutError, ConfigError) rather than resolving with a failure value.
+ *
+ * @param {OpenConnectionOptions} args
+ * @returns {Promise<Connection>}
+ */
+export function openConnection({ url, connect, proxy, trust, deadlines, tls, alpn, resumption, deps, signal, limits, now, }: OpenConnectionOptions): Promise<Connection>;
+/**
+ * The delegation decision, with the disqualifying reason spelled out so a caller's error can
+ * quote it. Discriminated on `ok` so `reason` is a string exactly when there is one.
+ * @typedef {{ ok: true, reason: null } | { ok: false, reason: string }} NativeFetchVerdict
+ */
+/**
+ * @typedef {object} NativeFetchQuery
+ * @property {import('./proxy/index.js').ProxyConfig | string | null} [proxy]
+ * @property {import('./trust/index.js').TrustConfig | null} [trust]
+ * @property {import('./tls/connect.js').TlsOptions | null} [tls]
+ * @property {boolean} [forceTunnel]
+ */
+/**
+ * Can the platform's own fetch() satisfy this request in full?
+ *
+ * Delegating to the native implementation when it can is strictly better — it is faster, does not
+ * burn metered CPU, speaks HTTP/2 and /3, and reaches origins our raw sockets are forbidden from
+ * dialling. But delegation must be decided on CAPABILITY, not merely on "is there a proxy":
+ * quietly satisfying a request that asked for a pinned certificate by handing it to an
+ * implementation using a different trust store would answer a security question the caller did
+ * not ask. So anything the native path cannot honour disqualifies it.
+ *
+ * @param {NativeFetchQuery} query
+ * @returns {NativeFetchVerdict}
+ */
+export function nativeFetchCanServe({ proxy, trust, tls, forceTunnel }: NativeFetchQuery): NativeFetchVerdict;
+/**
+ * A request URL reduced to what the transport dials.
+ */
+export type TransportTarget = {
+    url: URL;
+    /**
+     * IPv6 unbracketed, as the socket API and SOCKS5 want it
+     */
+    hostname: string;
+    /**
+     * explicit port, or the scheme default
+     */
+    port: number;
+    /**
+     * whether the scheme is https:
+     */
+    secure: boolean;
+};
+/**
+ * What a Response's `tunnelfetch` detail reports about the connection, before the HTTP layer
+ * adds the per-response httpVersion and framing.
+ */
+export type ConnectionInfo = {
+    url: string;
+    proxied: boolean;
+    /**
+     * the proxy actually used, credentials omitted
+     */
+    proxy: string | null;
+    /**
+     * null for cleartext
+     */
+    tls: import("./tls/connect.js").TlsSessionInfo | null;
+};
+/**
+ * A live connection carrying application bytes: the duplex, its provenance, and the deadline
+ * controller that governs it. This is what the pool stores and what sendAndReceive consumes.
+ */
+export type Connection = {
+    readable: ReadableStream<Uint8Array>;
+    writable: WritableStream<Uint8Array>;
+    close: () => Promise<void> | void;
+    info: ConnectionInfo;
+    /**
+     * TLS only;
+     * null when trust mode 'none' accepted a leaf it could not parse
+     */
+    peerCertificate?: import("./trust/index.js").ParsedCertificate | null | undefined;
+    deadlines: DeadlineController;
+    /**
+     * whether this call created the controller (and must dispose
+     * it) rather than borrowing the caller's
+     */
+    ownsDeadlines: boolean;
+};
+export type OpenConnectionOptions = {
+    url: string | URL;
+    /**
+     * injected socket factory
+     */
+    connect: import("./proxy/index.js").ConnectFn;
+    proxy?: string | import("./proxy/index.js").ProxyConfig | null | undefined;
+    /**
+     * the `verify=`-style knob, passed
+     * through to the trust layer
+     */
+    trust?: import("./trust/index.js").TrustConfig | undefined;
+    /**
+     * borrow the request's controller; omitting it makes
+     * this call own (and dispose) a fresh one
+     */
+    deadlines?: DeadlineController | undefined;
+    /**
+     * handshake options
+     */
+    tls?: import("./tls/connect.js").TlsOptions | undefined;
+    /**
+     * the ALPN protocol list to offer, newest/most-preferred first.
+     * Kept separate from `tls` so offering `h2` does not read as a user-supplied TLS option (which
+     * would disable native-fetch delegation and enter the pool key). `tls.alpn` still wins if set.
+     */
+    alpn?: string[] | undefined;
+    /**
+     * session-resumption wiring, injected per connection by the Client. Separate from `tls` for
+     * the same reason `alpn` is: it must neither disable native-fetch delegation nor enter the
+     * pool key — it is not caller configuration, it is state the Client derived FROM the pool key.
+     */
+    resumption?: {
+        offer?: import("./tls/connect.js").ResumptionOffer | null;
+        onTicket?: (t: import("./tls/connect.js").CapturedTicket) => void;
+    } | undefined;
+    /**
+     * injectable randomness/keygen for
+     * reproducible handshakes
+     */
+    deps?: import("./tls/connect.js").TlsDeps | undefined;
+    signal?: AbortSignal | undefined;
+    /**
+     * cap on the proxy CONNECT reply head
+     */
+    limits?: {
+        maxProxyReplyBytes?: number;
+    } | undefined;
+    /**
+     * epoch ms override for certificate validity
+     */
+    now?: number | undefined;
+};
+/**
+ * The delegation decision, with the disqualifying reason spelled out so a caller's error can
+ * quote it. Discriminated on `ok` so `reason` is a string exactly when there is one.
+ */
+export type NativeFetchVerdict = {
+    ok: true;
+    reason: null;
+} | {
+    ok: false;
+    reason: string;
+};
+export type NativeFetchQuery = {
+    proxy?: string | import("./proxy/index.js").ProxyConfig | null | undefined;
+    trust?: import("./trust/index.js").TrustConfig | null | undefined;
+    tls?: import("./tls/connect.js").TlsOptions | null | undefined;
+    forceTunnel?: boolean | undefined;
+};
+import { DeadlineController } from './util/deadline.js';

package/types/trust/der.d.ts

@@ -0,0 +1,239 @@
+/**
+ * One decoded tag-length-value element, as byte ranges into the ORIGINAL buffer. Every reader
+ * in the trust layer passes these around instead of slices precisely so that signature checks
+ * always run over the peer's own bytes.
+ * @typedef {object} Tlv
+ * @property {number} cls tag class, per {@link CLS}
+ * @property {boolean} constructed
+ * @property {number} tag tag number, high-tag-number form already decoded
+ * @property {number} start offset of the first header byte
+ * @property {number} headerLen tag + length octets
+ * @property {number} contentStart
+ * @property {number} contentEnd
+ * @property {number} end one past the element; equals contentEnd for every legal DER element
+ */
+/**
+ * Describe a tag for error messages: "SEQUENCE", "[0]", "APPLICATION 3".
+ * @param {number} cls
+ * @param {number} tag
+ * @returns {string}
+ */
+export function tagName(cls: number, tag: number): string;
+/**
+ * @param {number} offset
+ * @param {string} message
+ * @returns {CertificateError}
+ */
+export function parseError(offset: number, message: string): CertificateError;
+/**
+ * Read one TLV starting at `offset`. Returns byte ranges only — content is always a subarray of
+ * the caller's original buffer, never a copy, so signatures can be verified over the same bytes
+ * the peer sent.
+ *
+ * @param {Uint8Array} bytes
+ * @param {number} offset
+ * @returns {Tlv}
+ */
+export function readTlv(bytes: Uint8Array, offset: number): Tlv;
+/**
+ * Assert a TLV has the given shape, with an error naming expected vs got at the offset.
+ * @param {Tlv} tlv
+ * @param {{ cls?: number, tag: number, constructed?: boolean }} shape omitted `constructed`
+ *   accepts either form
+ * @param {string} what
+ * @returns {Tlv} the same tlv, for chaining into a reader
+ */
+export function expectTlv(tlv: Tlv, { cls, tag, constructed }: {
+    cls?: number;
+    tag: number;
+    constructed?: boolean;
+}, what: string): Tlv;
+/**
+ * Read a TLV and require it to be a constructed SEQUENCE.
+ * @param {Uint8Array} bytes
+ * @param {number} offset
+ * @param {string} [what]
+ * @returns {Tlv}
+ */
+export function readSequence(bytes: Uint8Array, offset: number, what?: string): Tlv;
+/**
+ * Parse the content of a constructed element into its immediate children, requiring them to fill
+ * the content exactly. Trailing bytes inside a container are as suspicious as trailing bytes
+ * after the certificate.
+ * @param {Uint8Array} bytes
+ * @param {Tlv} tlv
+ * @param {string} [what]
+ * @returns {Tlv[]}
+ */
+export function children(bytes: Uint8Array, tlv: Tlv, what?: string): Tlv[];
+/**
+ * Read the single top-level element and reject trailing bytes after it.
+ * @param {Uint8Array} bytes
+ * @param {string} [what]
+ * @returns {Tlv}
+ */
+export function readAll(bytes: Uint8Array, what?: string): Tlv;
+/**
+ * INTEGER: returns the raw big-endian content and, when it fits a safe JS number, the value.
+ * DER minimality: the first nine bits must not be all-zero or all-one, else a shorter encoding
+ * exists. Laxness here would let two different byte strings claim the same serial number.
+ * @param {Uint8Array} bytes
+ * @param {Tlv} tlv
+ * @param {string} [what]
+ * @returns {{ bytes: Uint8Array, value: number | null, negative: boolean }} `value` is null
+ *   when the magnitude does not fit a safe number (serials routinely do not)
+ */
+export function readInteger(bytes: Uint8Array, tlv: Tlv, what?: string): {
+    bytes: Uint8Array;
+    value: number | null;
+    negative: boolean;
+};
+/**
+ * OBJECT IDENTIFIER to dotted string. Sub-identifiers are base-128 and must be minimal: a leading
+ * 0x80 continuation byte is a second spelling of the same OID, and two spellings of one identity
+ * is how "unknown critical extension" checks get bypassed.
+ * @param {Uint8Array} bytes
+ * @param {Tlv} tlv
+ * @param {string} [what]
+ * @returns {string} dotted form, e.g. '2.5.29.15'
+ */
+export function readOid(bytes: Uint8Array, tlv: Tlv, what?: string): string;
+/**
+ * BIT STRING: unused-bit count + payload. DER additionally requires the unused bits themselves to
+ * be zero — a nonzero padding bit is another two-spellings ambiguity.
+ * @param {Uint8Array} bytes
+ * @param {Tlv} tlv
+ * @param {string} [what]
+ * @returns {{ unusedBits: number, bytes: Uint8Array }}
+ */
+export function readBitString(bytes: Uint8Array, tlv: Tlv, what?: string): {
+    unusedBits: number;
+    bytes: Uint8Array;
+};
+/**
+ * BOOLEAN. DER: content is exactly one byte, 0x00 or 0xff.
+ * @param {Uint8Array} bytes
+ * @param {Tlv} tlv
+ * @param {string} [what]
+ * @returns {boolean}
+ */
+export function readBoolean(bytes: Uint8Array, tlv: Tlv, what?: string): boolean;
+/**
+ * UTCTime, RFC 5280 profile: exactly YYMMDDHHMMSSZ. Seconds are mandatory, the zone is mandatory
+ * and must be Z, and fractional seconds do not exist in this profile. The two-digit year pivots
+ * at 50: 50..99 map to 19xx, 00..49 to 20xx (RFC 5280 s4.1.2.5.1).
+ * @param {Uint8Array} bytes
+ * @param {Tlv} tlv
+ * @param {string} [what]
+ * @returns {number} epoch ms UTC
+ */
+export function readUtcTime(bytes: Uint8Array, tlv: Tlv, what?: string): number;
+/**
+ * GeneralizedTime, RFC 5280 profile: exactly YYYYMMDDHHMMSSZ. Fractional seconds are explicitly
+ * forbidden by RFC 5280 s4.1.2.5.2, and allowing them would give one instant many encodings.
+ * @param {Uint8Array} bytes
+ * @param {Tlv} tlv
+ * @param {string} [what]
+ * @returns {number} epoch ms UTC
+ */
+export function readGeneralizedTime(bytes: Uint8Array, tlv: Tlv, what?: string): number;
+/**
+ * Either time type, as used by Validity and by name-constraint-free consumers.
+ * @param {Uint8Array} bytes
+ * @param {Tlv} tlv
+ * @param {string} [what]
+ * @returns {number} epoch ms UTC
+ */
+export function readTime(bytes: Uint8Array, tlv: Tlv, what?: string): number;
+/**
+ * Directory string types. Each type's alphabet is enforced — a PrintableString smuggling bytes
+ * outside its charset is two parsers disagreeing about one name.
+ *
+ * TeletexString is decoded as Latin-1: its real charset (T.61) is a negotiation-dependent mess
+ * that no CA has honoured in decades, and Latin-1 is the universal de-facto reading.
+ * @param {Uint8Array} bytes
+ * @param {Tlv} tlv
+ * @param {string} [what]
+ * @returns {string}
+ */
+export function readString(bytes: Uint8Array, tlv: Tlv, what?: string): string;
+/**
+ * ECDSA-Sig-Value (SEQUENCE of two INTEGERs) to the fixed-width r||s form WebCrypto verifies.
+ *
+ * This lives here, once, because both users of it are checking signatures: the certificate path
+ * builder and the TLS CertificateVerify. TLS transmits ECDSA signatures in DER while WebCrypto
+ * accepts only the P1363 concatenation, and a round-trip test that signs and verifies with
+ * WebCrypto agrees with itself while failing against every real server — so this conversion is
+ * exactly the sort of thing that must have one implementation and not two.
+ *
+ * Any malformation is an invalid signature; there is no "close enough" for signature bytes.
+ *
+ * @param {Uint8Array} sig DER ECDSA-Sig-Value
+ * @param {number} orderLen byte width of the curve order (32 / 48 / 66)
+ * @param {(why: string) => Error} onInvalid builds the caller's own error type
+ * @returns {Uint8Array} r||s, each half left-padded to orderLen
+ */
+export function ecdsaDerToRaw(sig: Uint8Array, orderLen: number, onInvalid: (why: string) => Error): Uint8Array;
+export namespace TAG {
+    let BOOLEAN: number;
+    let INTEGER: number;
+    let BIT_STRING: number;
+    let OCTET_STRING: number;
+    let NULL: number;
+    let OID: number;
+    let ENUMERATED: number;
+    let UTF8_STRING: number;
+    let SEQUENCE: number;
+    let SET: number;
+    let NUMERIC_STRING: number;
+    let PRINTABLE_STRING: number;
+    let TELETEX_STRING: number;
+    let IA5_STRING: number;
+    let UTC_TIME: number;
+    let GENERALIZED_TIME: number;
+    let VISIBLE_STRING: number;
+    let BMP_STRING: number;
+}
+export namespace CLS {
+    let UNIVERSAL: number;
+    let APPLICATION: number;
+    let CONTEXT: number;
+    let PRIVATE: number;
+}
+/** The content bytes of a TLV, as a subarray of the original buffer. */
+/** @type {(bytes: Uint8Array, tlv: Tlv) => Uint8Array} */
+export const content: (bytes: Uint8Array, tlv: Tlv) => Uint8Array;
+/** The full element (tag + length + content), as a subarray of the original buffer. */
+/** @type {(bytes: Uint8Array, tlv: Tlv) => Uint8Array} */
+export const element: (bytes: Uint8Array, tlv: Tlv) => Uint8Array;
+/**
+ * One decoded tag-length-value element, as byte ranges into the ORIGINAL buffer. Every reader
+ * in the trust layer passes these around instead of slices precisely so that signature checks
+ * always run over the peer's own bytes.
+ */
+export type Tlv = {
+    /**
+     * tag class, per {@link CLS}
+     */
+    cls: number;
+    constructed: boolean;
+    /**
+     * tag number, high-tag-number form already decoded
+     */
+    tag: number;
+    /**
+     * offset of the first header byte
+     */
+    start: number;
+    /**
+     * tag + length octets
+     */
+    headerLen: number;
+    contentStart: number;
+    contentEnd: number;
+    /**
+     * one past the element; equals contentEnd for every legal DER element
+     */
+    end: number;
+};
+import { CertificateError } from '../errors.js';