@bsv/wallet-toolbox 2.13.0 → 2.13.2

package/out/src/services/chaintracker/chaintracks/GoChaintracksServiceClient.js

@@ -2,6 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GoChaintracksServiceClient = void 0;
 const utilityHelpers_noBuffer_1 = require("../../../utility/utilityHelpers.noBuffer");
+const blockHeaderUtilities_1 = require("./util/blockHeaderUtilities");
+const safeDiagnostic_1 = require("./util/safeDiagnostic");
 /**
  * Client for go-chaintracks compatible HTTP services, including Arcade's
  * `/chaintracks/v2` surface. Unlike the legacy ChaintracksServiceClient, this
@@ -10,20 +12,44 @@ const utilityHelpers_noBuffer_1 = require("../../../utility/utilityHelpers.noBuf
  */
 class GoChaintracksServiceClient {
     chain;
+    /** SSE client; reorg registration is a supported additive capability. */
+    supportsReorgEvents = true;
+    static MAX_CONFIGURED_BYTES = 512 * 1024 * 1024;
+    static MAX_SUBSCRIPTIONS = 100_000;
     baseUrl;
     fetcher;
     requestTimeoutMsecs;
     reconnectWaitMsecs;
     reconnectWaitMaxMsecs;
+    maxJsonResponseBytes;
+    maxBinaryResponseBytes;
+    maxSseEventBytes;
+    maxReorgHeaders;
+    streamIdleTimeoutMsecs;
     subscriptions = new Map();
     nextSubscriptionId = 1;
     constructor(chain, serviceUrl, options = {}) {
         this.chain = chain;
-        let base = serviceUrl;
+        if (typeof chain !== 'string' || this.normalizeChain(chain) !== chain) {
+            throw new Error('chain must be a supported canonical ChainTracks network.');
+        }
+        if (options == null || typeof options !== 'object' || Array.isArray(options)) {
+            throw new Error('options must be a plain data object.');
+        }
+        const optionDescriptors = Object.getOwnPropertyDescriptors(options);
+        if (Object.values(optionDescriptors).some(descriptor => descriptor.get != null || descriptor.set != null)) {
+            throw new Error('options must contain accessor-free data properties.');
+        }
+        options = Object.freeze({ ...options });
+        const parsedServiceUrl = this.parseServiceUrl(serviceUrl);
+        let base = parsedServiceUrl.toString();
         while (base.endsWith('/'))
             base = base.slice(0, -1);
         let prefix = options.apiPrefix ?? '';
         if (prefix !== '') {
+            if (/[[\]\\?#]/.test(prefix) || prefix.split('/').some(part => part === '..' || part === '.')) {
+                throw new Error('apiPrefix must be an absolute URL path without traversal, query, or fragment.');
+            }
             if (!prefix.startsWith('/'))
                 prefix = `/${prefix}`;
             while (prefix.endsWith('/'))
@@ -31,16 +57,23 @@ class GoChaintracksServiceClient {
         }
         this.baseUrl = `${base}${prefix}`;
         this.fetcher = options.fetch ?? fetch;
+        if (typeof this.fetcher !== 'function')
+            throw new Error('fetch must be a function.');
         this.requestTimeoutMsecs = options.requestTimeoutMsecs ?? 30000;
         this.reconnectWaitMsecs = options.reconnectWaitMsecs ?? 1000;
         this.reconnectWaitMaxMsecs = options.reconnectWaitMaxMsecs ?? 60000;
+        this.maxJsonResponseBytes = this.readPositiveOption(options.maxJsonResponseBytes, 1024 * 1024, 'maxJsonResponseBytes', GoChaintracksServiceClient.MAX_CONFIGURED_BYTES);
+        this.maxBinaryResponseBytes = this.readPositiveOption(options.maxBinaryResponseBytes, 32 * 1024 * 1024, 'maxBinaryResponseBytes', GoChaintracksServiceClient.MAX_CONFIGURED_BYTES);
+        this.maxSseEventBytes = this.readPositiveOption(options.maxSseEventBytes, 1024 * 1024, 'maxSseEventBytes', GoChaintracksServiceClient.MAX_CONFIGURED_BYTES);
+        this.maxReorgHeaders = this.readPositiveOption(options.maxReorgHeaders, 4096, 'maxReorgHeaders', 100_000);
+        this.streamIdleTimeoutMsecs = this.readPositiveOption(options.streamIdleTimeoutMsecs, 45_000, 'streamIdleTimeoutMsecs', 60 * 60 * 1000);
         for (const [name, value] of [
             ['requestTimeoutMsecs', this.requestTimeoutMsecs],
             ['reconnectWaitMsecs', this.reconnectWaitMsecs],
             ['reconnectWaitMaxMsecs', this.reconnectWaitMaxMsecs]
         ]) {
-            if (!Number.isSafeInteger(value) || value < 1) {
-                throw new Error(`${name} must be a positive integer.`);
+            if (!Number.isSafeInteger(value) || value < 1 || value > 60 * 60 * 1000) {
+                throw new Error(`${name} must be a positive integer no greater than 3600000.`);
             }
         }
         if (this.reconnectWaitMaxMsecs < this.reconnectWaitMsecs) {
@@ -55,8 +88,16 @@ class GoChaintracksServiceClient {
         return h != null && root === (0, utilityHelpers_noBuffer_1.asString)(h.merkleRoot);
     }
     async getChain() {
-        const r = await this.getJson('/network');
-        return this.normalizeChain(typeof r === 'string' ? r : r.network);
+        const value = await this.getJson('/network');
+        const network = typeof value === 'string' ? value : this.readExactRecord(value, ['network'], 'network response').network;
+        if (typeof network !== 'string' || network.length > 64) {
+            throw new Error('ChainTracks upstream returned an invalid network.');
+        }
+        const actual = this.normalizeChain(network);
+        if (actual !== this.chain) {
+            throw new Error(`ChainTracks upstream network '${actual}' does not match configured chain '${this.chain}'.`);
+        }
+        return actual;
     }
     async getInfo() {
         const tip = await this.findChainTipHeader();
@@ -71,24 +112,60 @@ class GoChaintracksServiceClient {
         };
     }
     async getPresentHeight() {
-        const result = await this.getJson('/height');
-        return typeof result === 'number' ? result : result.height;
+        const value = await this.getJson('/height');
+        const height = typeof value === 'number' ? value : this.readExactRecord(value, ['height'], 'height response').height;
+        return this.validateHeight(height, 'upstream height');
     }
     async getHeaders(height, count) {
-        const bytes = await this.getBinary(`/headers.bin?height=${height}&count=${count}`);
+        this.validateHeight(height, 'height');
+        if (!Number.isSafeInteger(count) || count < 1) {
+            throw new Error('count must be a positive safe integer.');
+        }
+        if (count > Math.floor(this.maxBinaryResponseBytes / 80)) {
+            throw new Error('count exceeds the configured binary response limit.');
+        }
+        const bytes = await this.getBinary(`/headers.bin?height=${height}&count=${count}`, count * 80);
+        if (bytes.length % 80 !== 0) {
+            throw new Error('ChainTracks upstream returned a non-canonical binary header response.');
+        }
+        const headers = (0, blockHeaderUtilities_1.deserializeBlockHeaders)(height, bytes);
+        for (const [index, header] of headers.entries()) {
+            this.validateRemoteHeader(header, `binary header ${index}`);
+            if (index > 0 && header.previousHash !== headers[index - 1]?.hash) {
+                throw new Error('ChainTracks upstream returned an unlinked binary header response.');
+            }
+        }
         return (0, utilityHelpers_noBuffer_1.asString)(bytes);
     }
     async findChainTipHeader() {
-        return await this.getJson('/tip');
+        return this.validateRemoteHeader(await this.getJson('/tip'), 'chain tip');
     }
     async findChainTipHash() {
         return (await this.findChainTipHeader()).hash;
     }
     async findHeaderForHeight(height) {
-        return await this.getJsonOrUndefined(`/header/height/${height}`);
+        this.validateHeight(height, 'height');
+        const value = await this.getJsonOrUndefined(`/header/height/${height}`);
+        if (value === undefined)
+            return undefined;
+        const header = this.validateRemoteHeader(value, 'header-by-height response');
+        if (header.height !== height) {
+            throw new Error('ChainTracks upstream returned a header for the wrong height.');
+        }
+        return header;
     }
     async findHeaderForBlockHash(hash) {
-        return await this.getJsonOrUndefined(`/header/hash/${hash}`);
+        if (!/^[0-9a-fA-F]{64}$/.test(hash)) {
+            throw new Error('hash must be exactly 32 hexadecimal bytes.');
+        }
+        const value = await this.getJsonOrUndefined(`/header/hash/${hash}`);
+        if (value === undefined)
+            return undefined;
+        const header = this.validateRemoteHeader(value, 'header-by-hash response');
+        if (header.hash.toLowerCase() !== hash.toLowerCase()) {
+            throw new Error('ChainTracks upstream returned a header for the wrong hash.');
+        }
+        return header;
     }
     async addHeader(_header) {
         throw new Error('GoChaintracksServiceClient.addHeader is not supported by the remote v2 API.');
@@ -112,19 +189,52 @@ class GoChaintracksServiceClient {
         return await this.isListening();
     }
     async subscribeHeaders(listener) {
+        this.validateListener(listener);
         return this.subscribe('header', '/tip/stream', payload => {
-            listener(payload);
+            listener(this.validateRemoteHeader(payload, 'tip stream event'));
         });
     }
     async subscribeReorgs(listener) {
+        this.validateListener(listener);
         return this.subscribe('reorg', '/reorg/stream', payload => {
-            const event = payload;
-            if (event.oldTip != null && event.newTip != null) {
-                listener(event.depth ?? 0, event.oldTip, event.newTip, event.deactivatedHeaders);
+            const event = this.readExactRecord(payload, ['depth', 'oldTip', 'newTip', 'deactivatedHeaders'], 'reorg stream event', ['deactivatedHeaders']);
+            const depth = event.depth;
+            if (!Number.isSafeInteger(depth) || depth < 0 || depth > this.maxReorgHeaders) {
+                throw new Error('ChainTracks upstream returned an invalid reorg depth.');
+            }
+            const oldTip = this.validateRemoteHeader(event.oldTip, 'reorg old tip');
+            const newTip = this.validateRemoteHeader(event.newTip, 'reorg new tip');
+            let deactivatedHeaders;
+            if (event.deactivatedHeaders !== undefined) {
+                if (!Array.isArray(event.deactivatedHeaders) || event.deactivatedHeaders.length > this.maxReorgHeaders) {
+                    throw new Error('ChainTracks upstream returned an invalid deactivated-header list.');
+                }
+                deactivatedHeaders = event.deactivatedHeaders.map((header, index) => this.validateRemoteHeader(header, `deactivated header ${index}`));
+                if (deactivatedHeaders.length > depth) {
+                    throw new Error('ChainTracks upstream returned more deactivated headers than the reorg depth.');
+                }
+                if (deactivatedHeaders.length > 0 && deactivatedHeaders[0].hash !== oldTip.hash) {
+                    throw new Error('ChainTracks upstream returned a deactivated-header list that does not start at the old tip.');
+                }
+                const seen = new Set();
+                for (let index = 0; index < deactivatedHeaders.length; index++) {
+                    const header = deactivatedHeaders[index];
+                    if (seen.has(header.hash))
+                        throw new Error('ChainTracks upstream returned duplicate deactivated headers.');
+                    seen.add(header.hash);
+                    const parent = deactivatedHeaders[index + 1];
+                    if (parent != null && (header.height !== parent.height + 1 || header.previousHash !== parent.hash)) {
+                        throw new Error('ChainTracks upstream returned an unlinked deactivated-header list.');
+                    }
+                }
             }
+            listener(depth, oldTip, newTip, deactivatedHeaders);
         });
     }
     async unsubscribe(subscriptionId) {
+        if (typeof subscriptionId !== 'string' || subscriptionId.length === 0 || subscriptionId.length > 128) {
+            throw new Error('subscriptionId must be a non-empty bounded string.');
+        }
         const sub = this.subscriptions.get(subscriptionId);
         if (sub == null)
             return false;
@@ -134,6 +244,12 @@ class GoChaintracksServiceClient {
         return true;
     }
     async subscribe(type, path, onPayload) {
+        if (this.subscriptions.size >= GoChaintracksServiceClient.MAX_SUBSCRIPTIONS) {
+            throw new Error('ChainTracks subscription capacity has been reached.');
+        }
+        if (!Number.isSafeInteger(this.nextSubscriptionId) || this.nextSubscriptionId < 1) {
+            throw new Error('ChainTracks subscription id space has been exhausted.');
+        }
         const id = `${type}-${this.nextSubscriptionId++}`;
         const abort = new AbortController();
         const done = this.runSseWithReconnect(path, abort.signal, onPayload);
@@ -192,23 +308,28 @@ class GoChaintracksServiceClient {
         try {
             const response = await this.fetcher(this.url(path), {
                 headers: { Accept: 'text/event-stream' },
+                redirect: 'error',
                 signal: controller.signal
             });
             clearTimeout(timeout);
             if (!response.ok) {
-                throw new Error(`GET ${this.url(path)} failed ${response.status} ${response.statusText}`);
+                await response.body?.cancel().catch(() => { });
+                throw new Error(`GET ${this.url(path)} failed ${response.status} ${(0, safeDiagnostic_1.safeDiagnostic)(response.statusText, 128)}`);
             }
             if (response.body == null) {
                 throw new Error(`GET ${this.url(path)} returned no response body`);
             }
             const reader = response.body.getReader();
-            const decoder = new TextDecoder();
+            const decoder = new TextDecoder('utf-8', { fatal: true });
             let buffer = '';
             try {
                 for (;;) {
-                    const { done, value } = await reader.read();
+                    const { done, value } = await this.readStreamChunk(reader, controller.signal, this.streamIdleTimeoutMsecs);
                     if (done)
                         break;
+                    if (value.byteLength > this.maxSseEventBytes) {
+                        throw new Error('ChainTracks upstream SSE chunk exceeds the configured byte limit.');
+                    }
                     buffer += decoder.decode(value, { stream: true });
                     buffer = this.processSseBuffer(buffer, observePayload);
                 }
@@ -216,11 +337,13 @@ class GoChaintracksServiceClient {
                 this.processSseBuffer(`${buffer}\n\n`, observePayload);
             }
             finally {
+                await reader.cancel().catch(() => { });
                 reader.releaseLock();
             }
         }
         finally {
             clearTimeout(timeout);
+            controller.abort();
             signal.removeEventListener('abort', onAbort);
         }
         return receivedEvent;
@@ -229,9 +352,12 @@ class GoChaintracksServiceClient {
         buffer = buffer.replaceAll('\r\n', '\n');
         for (;;) {
             const boundary = buffer.indexOf('\n\n');
-            if (boundary < 0)
+            if (boundary < 0) {
+                this.assertSseSize(buffer);
                 return buffer;
+            }
             const eventText = buffer.slice(0, boundary);
+            this.assertSseSize(eventText);
             buffer = buffer.slice(boundary + 2);
             const data = eventText
                 .split(/\r?\n/)
@@ -240,12 +366,15 @@ class GoChaintracksServiceClient {
                 .join('\n');
             if (data === '')
                 continue;
+            let payload;
             try {
-                onPayload(JSON.parse(data));
+                payload = JSON.parse(data);
             }
             catch {
                 // Ignore malformed events; the next SSE event can still be valid.
+                continue;
             }
+            onPayload(payload);
         }
     }
     async getJson(path) {
@@ -255,43 +384,246 @@ class GoChaintracksServiceClient {
         return r;
     }
     async getJsonOrUndefined(path) {
-        const response = await this.fetchWithTimeout(this.url(path), { headers: { Accept: 'application/json' } });
-        if (response.status === 404)
-            return undefined;
-        if (!response.ok) {
-            throw new Error(`GET ${this.url(path)} failed ${response.status} ${response.statusText}`);
-        }
-        const value = (await response.json());
-        if (value != null && typeof value === 'object' && 'status' in value) {
-            const envelope = value;
-            if (envelope.status === 'success')
-                return envelope.value;
-            if (envelope.status === 'error')
-                throw new Error(envelope.description ?? `GET ${this.url(path)} failed`);
-        }
-        return value;
+        return await this.consumeWithTimeout(this.url(path), { headers: { Accept: 'application/json' } }, async (response, signal) => {
+            if (response.status === 404) {
+                await response.body?.cancel().catch(() => { });
+                return undefined;
+            }
+            if (!response.ok) {
+                await response.body?.cancel().catch(() => { });
+                throw new Error(`GET ${this.url(path)} failed ${response.status} ${response.statusText}`);
+            }
+            const bytes = await this.readBoundedBody(response, this.maxJsonResponseBytes, signal);
+            let value;
+            try {
+                value = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+            }
+            catch {
+                throw new Error(`GET ${this.url(path)} returned invalid JSON.`);
+            }
+            if (this.isPlainRecord(value) && Object.hasOwn(value, 'status')) {
+                const envelope = this.readRecord(value, ['status', 'value', 'code', 'description'], 'legacy ChainTracks envelope');
+                if (envelope.status === 'success' && Object.hasOwn(envelope, 'value')) {
+                    return envelope.value;
+                }
+                if (envelope.status === 'error') {
+                    const description = envelope.description;
+                    if (description !== undefined && (typeof description !== 'string' || description.length > 4096)) {
+                        throw new Error('ChainTracks upstream returned an invalid error envelope.');
+                    }
+                    throw new Error(typeof description === 'string' ? (0, safeDiagnostic_1.safeDiagnostic)(description) : `GET ${this.url(path)} failed`);
+                }
+                throw new Error('ChainTracks upstream returned an invalid legacy envelope.');
+            }
+            return value;
+        });
     }
-    async getBinary(path) {
-        const response = await this.fetchWithTimeout(this.url(path), { headers: { Accept: 'application/octet-stream' } });
-        if (!response.ok) {
-            throw new Error(`GET ${this.url(path)} failed ${response.status} ${response.statusText}`);
-        }
-        return new Uint8Array(await response.arrayBuffer());
+    async getBinary(path, expectedMaximum) {
+        const maximum = Math.min(this.maxBinaryResponseBytes, expectedMaximum);
+        return await this.consumeWithTimeout(this.url(path), { headers: { Accept: 'application/octet-stream' } }, async (response, signal) => {
+            if (!response.ok) {
+                await response.body?.cancel().catch(() => { });
+                throw new Error(`GET ${this.url(path)} failed ${response.status} ${(0, safeDiagnostic_1.safeDiagnostic)(response.statusText, 128)}`);
+            }
+            return await this.readBoundedBody(response, maximum, signal);
+        });
     }
-    async fetchWithTimeout(url, init) {
+    async consumeWithTimeout(url, init, consume) {
         const controller = new AbortController();
         const timeout = setTimeout(() => controller.abort(), this.requestTimeoutMsecs);
         try {
-            return await this.fetcher(url, { ...init, signal: controller.signal });
+            const response = await this.fetcher(url, {
+                ...init,
+                redirect: 'error',
+                signal: controller.signal
+            });
+            return await consume(response, controller.signal);
         }
         finally {
             clearTimeout(timeout);
+            controller.abort();
         }
     }
+    async readBoundedBody(response, maximum, signal) {
+        const contentLength = response.headers.get('content-length');
+        if (contentLength != null) {
+            if (!/^(0|[1-9]\d*)$/.test(contentLength)) {
+                throw new Error('ChainTracks upstream returned an invalid Content-Length.');
+            }
+            const declared = Number(contentLength);
+            if (!Number.isSafeInteger(declared) || declared > maximum) {
+                throw new Error('ChainTracks upstream response exceeds the configured byte limit.');
+            }
+        }
+        if (response.body == null)
+            return new Uint8Array(0);
+        const reader = response.body.getReader();
+        const chunks = [];
+        let length = 0;
+        try {
+            for (;;) {
+                const { done, value } = await this.readStreamChunk(reader, signal);
+                if (done)
+                    break;
+                if (!(value instanceof Uint8Array)) {
+                    throw new Error('ChainTracks upstream returned a non-byte response body.');
+                }
+                length += value.byteLength;
+                if (!Number.isSafeInteger(length) || length > maximum) {
+                    throw new Error('ChainTracks upstream response exceeds the configured byte limit.');
+                }
+                chunks.push(value);
+            }
+        }
+        finally {
+            await reader.cancel().catch(() => { });
+            reader.releaseLock();
+        }
+        const result = new Uint8Array(length);
+        let offset = 0;
+        for (const chunk of chunks) {
+            result.set(chunk, offset);
+            offset += chunk.byteLength;
+        }
+        return result;
+    }
+    async readStreamChunk(reader, signal, idleTimeoutMsecs) {
+        if (signal.aborted)
+            throw this.abortError();
+        return await new Promise((resolve, reject) => {
+            let settled = false;
+            let timeout;
+            const finish = (action, value) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (timeout != null)
+                    clearTimeout(timeout);
+                signal.removeEventListener('abort', onAbort);
+                action(value);
+            };
+            const onAbort = () => finish(reject, this.abortError());
+            signal.addEventListener('abort', onAbort, { once: true });
+            if (idleTimeoutMsecs != null) {
+                timeout = setTimeout(() => finish(reject, new Error('ChainTracks upstream stream exceeded its idle timeout.')), idleTimeoutMsecs);
+            }
+            reader.read().then(result => finish(resolve, result), error => finish(reject, error instanceof Error ? error : new Error(String(error))));
+        });
+    }
+    abortError() {
+        const error = new Error('ChainTracks upstream request exceeded its deadline.');
+        error.name = 'AbortError';
+        return error;
+    }
+    assertSseSize(value) {
+        if (new TextEncoder().encode(value).byteLength > this.maxSseEventBytes) {
+            throw new Error('ChainTracks upstream SSE event exceeds the configured byte limit.');
+        }
+    }
+    validateHeight(value, name) {
+        if (!Number.isSafeInteger(value) || value < 0 || value > 0x7fffffff) {
+            throw new Error(`${name} must be an integer between 0 and 2147483647.`);
+        }
+        return value;
+    }
+    validateRemoteHeader(value, name) {
+        const baseKeys = ['version', 'previousHash', 'merkleRoot', 'time', 'bits', 'nonce', 'height', 'hash'];
+        const liveKeys = ['chainWork', 'isChainTip', 'isActive', 'headerId', 'previousHeaderId'];
+        const record = this.readExactRecord(value, [...baseKeys, ...liveKeys], name, liveKeys);
+        const presentLiveKeys = liveKeys.filter(key => Object.hasOwn(record, key));
+        if ((presentLiveKeys.length !== 0 && presentLiveKeys.length !== liveKeys.length) ||
+            (record.chainWork !== undefined &&
+                (typeof record.chainWork !== 'string' || !/^[0-9a-fA-F]{64}$/.test(record.chainWork))) ||
+            (record.isChainTip !== undefined && typeof record.isChainTip !== 'boolean') ||
+            (record.isActive !== undefined && typeof record.isActive !== 'boolean') ||
+            (record.headerId !== undefined && (!Number.isSafeInteger(record.headerId) || record.headerId < 1)) ||
+            (record.previousHeaderId !== undefined &&
+                record.previousHeaderId !== null &&
+                (!Number.isSafeInteger(record.previousHeaderId) || record.previousHeaderId < 1))) {
+            throw new Error(`ChainTracks upstream returned an invalid ${name}.`);
+        }
+        const header = {
+            version: record.version,
+            previousHash: record.previousHash,
+            merkleRoot: record.merkleRoot,
+            time: record.time,
+            bits: record.bits,
+            nonce: record.nonce,
+            height: record.height,
+            hash: record.hash
+        };
+        try {
+            (0, blockHeaderUtilities_1.validateHeaderFormat)(header);
+            (0, blockHeaderUtilities_1.validateHeaderProofOfWork)(header);
+        }
+        catch (error) {
+            throw new Error(`ChainTracks upstream returned an invalid ${name}: ${(0, safeDiagnostic_1.safeDiagnostic)(error)}`);
+        }
+        const result = { ...header };
+        for (const key of liveKeys) {
+            if (record[key] !== undefined)
+                result[key] = record[key];
+        }
+        return result;
+    }
+    isPlainRecord(value) {
+        if (value == null || typeof value !== 'object' || Array.isArray(value))
+            return false;
+        const prototype = Object.getPrototypeOf(value);
+        return prototype === Object.prototype || prototype === null;
+    }
+    readRecord(value, allowedKeys, name) {
+        if (!this.isPlainRecord(value))
+            throw new Error(`ChainTracks upstream returned an invalid ${name}.`);
+        const descriptors = Object.getOwnPropertyDescriptors(value);
+        if (Object.keys(descriptors).some(key => !allowedKeys.includes(key) || descriptors[key]?.get != null || descriptors[key]?.set != null)) {
+            throw new Error(`ChainTracks upstream returned an invalid ${name}.`);
+        }
+        return value;
+    }
+    readExactRecord(value, allowedKeys, name, optionalKeys = []) {
+        const record = this.readRecord(value, allowedKeys, name);
+        const requiredKeys = allowedKeys.filter(key => !optionalKeys.includes(key));
+        if (!requiredKeys.every(key => Object.hasOwn(record, key))) {
+            throw new Error(`ChainTracks upstream returned an invalid ${name}.`);
+        }
+        return record;
+    }
+    readPositiveOption(value, fallback, name, maximum) {
+        const resolved = value ?? fallback;
+        if (!Number.isSafeInteger(resolved) || resolved < 1 || resolved > maximum) {
+            throw new Error(`${name} must be an integer between 1 and ${maximum}.`);
+        }
+        return resolved;
+    }
+    validateListener(listener) {
+        if (typeof listener !== 'function')
+            throw new Error('listener must be a function.');
+    }
+    parseServiceUrl(serviceUrl) {
+        let parsed;
+        try {
+            parsed = new URL(serviceUrl);
+        }
+        catch {
+            throw new Error('serviceUrl must be an absolute HTTP(S) URL.');
+        }
+        if (!['http:', 'https:'].includes(parsed.protocol) ||
+            parsed.username !== '' ||
+            parsed.password !== '' ||
+            parsed.search !== '' ||
+            parsed.hash !== '') {
+            throw new Error('serviceUrl must be an HTTP(S) URL without credentials, query, or fragment.');
+        }
+        return parsed;
+    }
     url(path) {
         return `${this.baseUrl}${path}`;
     }
     normalizeChain(network) {
+        if (typeof network !== 'string' || network.length > 64 || (0, safeDiagnostic_1.containsControlCharacter)(network)) {
+            throw new Error('ChainTracks upstream returned an invalid network.');
+        }
         switch (network.trim().toLowerCase()) {
             case 'main':
             case 'mainnet':