zapo-js 0.2.0 → 1.0.0

package/dist/esm/transport/noise/WaNoiseSession.js

@@ -7,13 +7,13 @@ import { buildLoginPayload, buildRegistrationPayload } from '../noise/WaClientPa
 import { WaFrameCodec } from '../noise/WaFrameCodec.js';
 import { verifyNoiseCertificateChain } from '../noise/WaNoiseCert.js';
 import { WaNoiseHandshake } from '../noise/WaNoiseHandshake.js';
-import { concatBytes, toBytesView } from '../../util/bytes.js';
+import { concatBytes } from '../../util/bytes.js';
 import { toError } from '../../util/primitives.js';
 function resolvePayload(payload) {
     if (payload instanceof Uint8Array) {
         return Promise.resolve(payload);
     }
-    return Promise.resolve(payload()).then((value) => toBytesView(value));
+    return Promise.resolve(payload());
 }
 async function resolveHandshakePayload(config) {
     if (config.isRegistered) {
@@ -48,7 +48,6 @@ function buildRoutingInfoPrefix(routingInfo) {
 export class WaNoiseSession {
     constructor(sendWire, logger = new ConsoleLogger('info')) {
         this.writeChain = Promise.resolve();
-        this.readChain = Promise.resolve();
         this.frameCodec = null;
         this.handshakeInbox = [];
         this.handshakeInboxHead = 0;
@@ -58,6 +57,7 @@ export class WaNoiseSession {
         this.closedError = null;
         this.noiseSocket = null;
         this.serverStaticKey = null;
+        this.trustedRootCa = undefined;
         this.handshakeFrameTimeoutMs = WA_DEFAULTS.CONNECT_TIMEOUT_MS;
         this.sendWire = sendWire;
         this.logger = logger;
@@ -68,9 +68,7 @@ export class WaNoiseSession {
             isRegistered: config.isRegistered,
             hasServerStaticKey: !!config.serverStaticKey
         });
-        const protocolHeader = config.protocolHeader
-            ? toBytesView(config.protocolHeader)
-            : WA_PROTO_HEADER;
+        const protocolHeader = config.protocolHeader ?? WA_PROTO_HEADER;
         const introFrame = config.routingInfo && config.routingInfo.length > 0
             ? concatBytes([buildRoutingInfoPrefix(config.routingInfo), protocolHeader])
             : protocolHeader;
@@ -80,17 +78,18 @@ export class WaNoiseSession {
             resolveHandshakePayload(config)
         ]);
         const verifyCertificates = config.verifyCertificateChain !== false;
+        this.trustedRootCa = config.trustedRootCa;
         if (config.serverStaticKey && config.serverStaticKey.length === 32) {
-            this.logger.info('noise session attempting resume handshake (IK)');
+            this.logger.debug('noise session attempting resume handshake (IK)');
             this.noiseSocket = await this.resumeHandshake(config.serverStaticKey, config.clientStaticKeyPair, ephemeralKeyPair, payload, protocolHeader, verifyCertificates);
             await this.decodeBufferedPostHandshakeFrames();
-            this.logger.info('noise session established via resume/full fallback path');
+            this.logger.info('noise session established', { mode: 'resume_or_fallback' });
             return;
         }
-        this.logger.info('noise session starting full handshake (XX)');
+        this.logger.debug('noise session starting full handshake (XX)');
         this.noiseSocket = await this.fullHandshake(config.clientStaticKeyPair, ephemeralKeyPair, payload, protocolHeader, verifyCertificates);
         await this.decodeBufferedPostHandshakeFrames();
-        this.logger.info('noise session established via full handshake');
+        this.logger.info('noise session established', { mode: 'full' });
     }
     encryptFrame(frame) {
         const socket = this.noiseSocket;
@@ -98,19 +97,11 @@ export class WaNoiseSession {
         if (!socket || !codec) {
             return Promise.reject(new Error('noise session is not established'));
         }
-        let encryptPromise;
-        try {
-            encryptPromise = socket.encrypt(socket.reserveWriteNonce(), frame);
-        }
-        catch (error) {
-            return Promise.reject(error);
-        }
-        const result = this.writeChain
-            .then(() => encryptPromise)
-            .then((encrypted) => codec.encodeFrame(encrypted));
+        const result = this.writeChain.then(() => codec.encodeFrame(socket.encrypt(frame)));
         this.writeChain = result.then(() => { }, () => { });
         return result;
     }
+    // eslint-disable-next-line @typescript-eslint/require-await
     async pushWireChunk(chunk) {
         const codec = this.frameCodec;
         if (!codec) {
@@ -139,11 +130,7 @@ export class WaNoiseSession {
             return out;
         }
         if (frames.length > 0) {
-            const decryptBatch = this.decryptFramesBatch(this.noiseSocket, frames);
-            this.readChain = this.readChain
-                .then(() => decryptBatch)
-                .then(() => { }, () => { });
-            const decrypted = await decryptBatch;
+            const decrypted = this.decryptFramesBatch(this.noiseSocket, frames);
             for (let i = 0; i < decrypted.length; i++) {
                 out.push(decrypted[i]);
             }
@@ -161,15 +148,12 @@ export class WaNoiseSession {
             rejecter(closeError);
         }
     }
-    async decryptFramesBatch(socket, frames) {
-        if (frames.length === 1) {
-            return [await socket.decrypt(socket.reserveReadNonce(), frames[0])];
-        }
-        const pending = new Array(frames.length);
+    decryptFramesBatch(socket, frames) {
+        const out = new Array(frames.length);
         for (let i = 0; i < frames.length; i++) {
-            pending[i] = socket.decrypt(socket.reserveReadNonce(), frames[i]);
+            out[i] = socket.decrypt(frames[i]);
         }
-        return Promise.all(pending);
+        return out;
     }
     reset() {
         this.logger.trace('noise session reset');
@@ -181,8 +165,8 @@ export class WaNoiseSession {
         this.closedError = null;
         this.noiseSocket = null;
         this.serverStaticKey = null;
+        this.trustedRootCa = undefined;
         this.writeChain = Promise.resolve();
-        this.readChain = Promise.resolve();
     }
     getServerStaticKey() {
         return this.serverStaticKey;
@@ -190,8 +174,8 @@ export class WaNoiseSession {
     async fullHandshake(clientStaticKeyPair, ephemeralKeyPair, payload, protocolHeader, verifyCertificates) {
         this.logger.trace('noise full handshake: send client hello');
         const handshake = new WaNoiseHandshake();
-        await handshake.start(NOISE_XX_NAME, protocolHeader);
-        await handshake.authenticate(ephemeralKeyPair.pubKey);
+        handshake.start(NOISE_XX_NAME, protocolHeader);
+        handshake.authenticate(ephemeralKeyPair.pubKey);
         const clientHello = proto.HandshakeMessage.encode({
             clientHello: {
                 ephemeral: ephemeralKeyPair.pubKey
@@ -205,23 +189,23 @@ export class WaNoiseSession {
         if (resumeResult.socket) {
             return resumeResult.socket;
         }
-        this.logger.info('noise resume handshake fallback to XX');
+        this.logger.debug('noise resume handshake fallback to XX');
         return this.resumeHandshakeWithFallback(clientStaticKeyPair, ephemeralKeyPair, payload, protocolHeader, resumeResult.serverHelloFrame, verifyCertificates);
     }
     async tryResumeHandshakeWithIk(serverStaticKey, clientStaticKeyPair, ephemeralKeyPair, payload, protocolHeader) {
         this.logger.trace('noise resume handshake: send IK client hello');
         const handshake = new WaNoiseHandshake();
-        await handshake.start(NOISE_IK_NAME, protocolHeader);
-        await handshake.authenticate(serverStaticKey);
-        await handshake.authenticate(ephemeralKeyPair.pubKey);
+        handshake.start(NOISE_IK_NAME, protocolHeader);
+        handshake.authenticate(serverStaticKey);
+        handshake.authenticate(ephemeralKeyPair.pubKey);
         const [agreement1, agreement2] = await Promise.all([
             X25519.scalarMult(ephemeralKeyPair.privKey, serverStaticKey),
             X25519.scalarMult(clientStaticKeyPair.privKey, serverStaticKey)
         ]);
-        await handshake.mixIntoKey(agreement1);
-        const encryptedClientStatic = await handshake.encrypt(clientStaticKeyPair.pubKey);
-        await handshake.mixIntoKey(agreement2);
-        const encryptedPayload = await handshake.encrypt(payload);
+        handshake.mixIntoKey(agreement1);
+        const encryptedClientStatic = handshake.encrypt(clientStaticKeyPair.pubKey);
+        handshake.mixIntoKey(agreement2);
+        const encryptedPayload = handshake.encrypt(payload);
         const clientHello = proto.HandshakeMessage.encode({
             clientHello: {
                 ephemeral: ephemeralKeyPair.pubKey,
@@ -244,23 +228,23 @@ export class WaNoiseSession {
         if (!serverHello.payload) {
             throw new Error('noise resume handshake missing certificate payload');
         }
-        const serverEphemeral = toBytesView(serverHello.ephemeral);
-        await handshake.authenticate(serverEphemeral);
+        const serverEphemeral = serverHello.ephemeral;
+        handshake.authenticate(serverEphemeral);
         const [dh1, dh2] = await Promise.all([
             X25519.scalarMult(ephemeralKeyPair.privKey, serverEphemeral),
             X25519.scalarMult(clientStaticKeyPair.privKey, serverEphemeral)
         ]);
-        await handshake.mixIntoKey(dh1);
-        await handshake.mixIntoKey(dh2);
-        await handshake.decrypt(toBytesView(serverHello.payload));
+        handshake.mixIntoKey(dh1);
+        handshake.mixIntoKey(dh2);
+        handshake.decrypt(serverHello.payload);
         this.serverStaticKey = serverStaticKey;
-        this.logger.info('noise resume handshake successful without fallback');
-        return { socket: await handshake.finish(), serverHelloFrame: null };
+        this.logger.debug('noise resume handshake successful without fallback');
+        return { socket: handshake.finish(), serverHelloFrame: null };
     }
     async resumeHandshakeWithFallback(clientStaticKeyPair, ephemeralKeyPair, payload, protocolHeader, serverHelloFrame, verifyCertificates) {
         const fallback = new WaNoiseHandshake();
-        await fallback.start(NOISE_XX_FALLBACK_NAME, protocolHeader);
-        await fallback.authenticate(ephemeralKeyPair.pubKey);
+        fallback.start(NOISE_XX_FALLBACK_NAME, protocolHeader);
+        fallback.authenticate(ephemeralKeyPair.pubKey);
         return this.continueFullHandshake(fallback, serverHelloFrame, clientStaticKeyPair, ephemeralKeyPair, payload, verifyCertificates);
     }
     async continueFullHandshake(handshake, serverHelloFrame, clientStaticKeyPair, ephemeralKeyPair, payload, verifyCertificates) {
@@ -270,20 +254,20 @@ export class WaNoiseSession {
         if (!serverHello?.ephemeral || !serverHello.static || !serverHello.payload) {
             throw new Error('noise full handshake missing server hello fields');
         }
-        const serverEphemeral = toBytesView(serverHello.ephemeral);
-        await handshake.authenticate(serverEphemeral);
-        await handshake.mixIntoKey(await X25519.scalarMult(ephemeralKeyPair.privKey, serverEphemeral));
-        const serverStatic = await handshake.decrypt(toBytesView(serverHello.static));
-        await handshake.mixIntoKey(await X25519.scalarMult(ephemeralKeyPair.privKey, serverStatic));
-        const certificate = await handshake.decrypt(toBytesView(serverHello.payload));
+        const serverEphemeral = serverHello.ephemeral;
+        handshake.authenticate(serverEphemeral);
+        handshake.mixIntoKey(await X25519.scalarMult(ephemeralKeyPair.privKey, serverEphemeral));
+        const serverStatic = handshake.decrypt(serverHello.static);
+        handshake.mixIntoKey(await X25519.scalarMult(ephemeralKeyPair.privKey, serverStatic));
+        const certificate = handshake.decrypt(serverHello.payload);
         if (verifyCertificates) {
-            await verifyNoiseCertificateChain(certificate, serverStatic);
+            await verifyNoiseCertificateChain(certificate, serverStatic, this.trustedRootCa);
             this.logger.trace('noise certificate chain verified');
         }
         this.serverStaticKey = serverStatic;
-        const encryptedClientStatic = await handshake.encrypt(clientStaticKeyPair.pubKey);
-        await handshake.mixIntoKey(await X25519.scalarMult(clientStaticKeyPair.privKey, serverEphemeral));
-        const encryptedPayload = await handshake.encrypt(payload);
+        const encryptedClientStatic = handshake.encrypt(clientStaticKeyPair.pubKey);
+        handshake.mixIntoKey(await X25519.scalarMult(clientStaticKeyPair.privKey, serverEphemeral));
+        const encryptedPayload = handshake.encrypt(payload);
         const clientFinish = proto.HandshakeMessage.encode({
             clientFinish: {
                 static: encryptedClientStatic,
@@ -346,6 +330,7 @@ export class WaNoiseSession {
             throw toError(error);
         });
     }
+    // eslint-disable-next-line @typescript-eslint/require-await
     async decodeBufferedPostHandshakeFrames() {
         if (!this.noiseSocket || this.handshakeInboxHead >= this.handshakeInbox.length) {
             return;
@@ -356,11 +341,7 @@ export class WaNoiseSession {
         const start = this.handshakeInboxHead;
         const frames = this.handshakeInbox.slice(start);
         if (frames.length > 0) {
-            const decryptBatch = this.decryptFramesBatch(this.noiseSocket, frames);
-            this.readChain = this.readChain
-                .then(() => decryptBatch)
-                .then(() => { }, () => { });
-            const decrypted = await decryptBatch;
+            const decrypted = this.decryptFramesBatch(this.noiseSocket, frames);
             for (let i = 0; i < decrypted.length; i++) {
                 this.pendingDecryptedFrames.push(decrypted[i]);
             }

package/dist/esm/transport/noise/WaNoiseSocket.js

@@ -1,21 +1,27 @@
-import { aesGcmDecrypt, aesGcmEncrypt, buildNonce } from '../../crypto/index.js';
+import { createSecretKey } from 'node:crypto';
+import { aesGcmDecrypt, aesGcmEncrypt, writeNonceCounter } from '../../crypto/index.js';
+/**
+ * Post-handshake symmetric channel: applies AES-GCM with per-direction
+ * 12-byte nonces (counter in the trailing 4 bytes) using a per-instance
+ * scratch buffer to avoid allocations on the hot path.
+ */
 export class WaNoiseSocket {
     constructor(encryptKey, decryptKey) {
-        this.encryptKey = encryptKey;
-        this.decryptKey = decryptKey;
+        this.writeNonceScratch = new Uint8Array(12);
+        this.readNonceScratch = new Uint8Array(12);
+        this.encryptKey = createSecretKey(encryptKey);
+        this.decryptKey = createSecretKey(decryptKey);
         this.writeCounter = 0;
         this.readCounter = 0;
     }
-    reserveWriteNonce() {
-        return buildNonce(this.writeCounter++);
+    /** Encrypts an outgoing `frame` with the next write nonce; advances the write counter. */
+    encrypt(frame, additionalData) {
+        writeNonceCounter(this.writeNonceScratch, this.writeCounter++);
+        return aesGcmEncrypt(this.encryptKey, this.writeNonceScratch, frame, additionalData);
     }
-    encrypt(nonce, frame, additionalData) {
-        return aesGcmEncrypt(this.encryptKey, nonce, frame, additionalData);
-    }
-    reserveReadNonce() {
-        return buildNonce(this.readCounter++);
-    }
-    decrypt(nonce, frame, additionalData) {
-        return aesGcmDecrypt(this.decryptKey, nonce, frame, additionalData);
+    /** Decrypts an incoming `frame` with the next read nonce; advances the read counter. */
+    decrypt(frame, additionalData) {
+        writeNonceCounter(this.readNonceScratch, this.readCounter++);
+        return aesGcmDecrypt(this.decryptKey, this.readNonceScratch, frame, additionalData);
     }
 }

package/dist/esm/transport/noise/constants.js

@@ -1,5 +1,4 @@
 import { TEXT_ENCODER } from '../../util/bytes.js';
-export const DEFAULT_VERSION_BASE = '2.3000.1034748654';
 export const WA_PROTO_HEADER = new Uint8Array([87, 65, 6, 3]);
 export const NOISE_XX_NAME = TEXT_ENCODER.encode('Noise_XX_25519_AESGCM_SHA256\0\0\0\0');
 export const NOISE_IK_NAME = TEXT_ENCODER.encode('Noise_IK_25519_AESGCM_SHA256\0\0\0\0');

package/dist/esm/transport/proxy.js

@@ -1,24 +1,29 @@
+/** Type guard for an undici-style proxy dispatcher (has `dispatch` method). */
 export function isProxyDispatcher(value) {
     return (typeof value === 'object' &&
         value !== null &&
         'dispatch' in value &&
         typeof value.dispatch === 'function');
 }
+/** Type guard for a Node http.Agent-style proxy (has `addRequest` method). */
 export function isProxyAgent(value) {
     return (typeof value === 'object' &&
         value !== null &&
         'addRequest' in value &&
         typeof value.addRequest === 'function');
 }
+/** Type guard accepting either {@link isProxyDispatcher} or {@link isProxyAgent} shapes. */
 export function isProxyTransport(value) {
     return isProxyDispatcher(value) || isProxyAgent(value);
 }
+/** Narrows `proxy` to {@link WaProxyDispatcher} or returns `undefined`. */
 export function toProxyDispatcher(proxy) {
     if (!proxy || !isProxyDispatcher(proxy)) {
         return undefined;
     }
     return proxy;
 }
+/** Narrows `proxy` to {@link WaProxyAgent} or returns `undefined`. */
 export function toProxyAgent(proxy) {
     if (!proxy || !isProxyAgent(proxy)) {
         return undefined;

package/dist/esm/transport/stream/parse.js

@@ -2,7 +2,6 @@ import { WA_STREAM_SIGNALING } from '../../protocol/constants.js';
 import { findNodeChild, hasNodeChild } from '../node/helpers.js';
 import { base64ToBytesChecked } from '../../util/bytes.js';
 import { parseOptionalInt } from '../../util/primitives.js';
-const DIGITS_ONLY_RE = /^\d+$/;
 export function parseStreamControlNode(node) {
     if (node.tag === WA_STREAM_SIGNALING.XML_STREAM_END_TAG) {
         return { kind: 'xmlstreamend' };
@@ -16,12 +15,9 @@ export function parseStreamControlNode(node) {
             ? { kind: 'stream_error_replaced' }
             : { kind: 'stream_error_device_removed' };
     }
-    const codeStr = node.attrs.code;
-    if (codeStr && DIGITS_ONLY_RE.test(codeStr)) {
-        const code = Number(codeStr);
-        if (Number.isSafeInteger(code)) {
-            return { kind: 'stream_error_code', code };
-        }
+    const code = parseOptionalInt(node.attrs.code);
+    if (code !== undefined) {
+        return { kind: 'stream_error_code', code };
     }
     const ackNode = findNodeChild(node, WA_STREAM_SIGNALING.ACK_TAG);
     if (ackNode) {

package/dist/esm/transport/wa-web-version-fetcher.js

@@ -0,0 +1,91 @@
+import { toProxyDispatcher } from './proxy.js';
+import { toError } from '../util/primitives.js';
+const DEFAULT_USER_AGENT = 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36';
+const DEFAULT_TIMEOUT_MS = 10000;
+const SW_JS_URL = 'https://web.whatsapp.com/sw.js';
+const CLIENT_REVISION_PATTERN = /\\?"client_revision\\?":\s*(\d+)/;
+/**
+ * Fetches the current WhatsApp Web `client_revision` from the public
+ * `sw.js` served by the WhatsApp Web frontend and assembles a
+ * `2.3000.x` version string suitable for `WaClientOptions.version`.
+ *
+ * Use this when the library's hardcoded default starts being rejected by
+ * the server with HTTP 405 / `failure_client_too_old`, and you need to
+ * refresh the version without waiting for a library bump.
+ *
+ * Network failures and parse errors throw; wrap in a `try`/`catch` and
+ * fall back to the hardcoded default.
+ *
+ * @example
+ * const latest = await fetchLatestWaWebVersion()
+ * const client = new WaClient({ store, sessionId, version: latest.version })
+ */
+export async function fetchLatestWaWebVersion(options = {}) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const dispatcher = toProxyDispatcher(options.proxy);
+    const fetchImpl = options.fetch ?? fetch;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(new Error(`fetch latest wa-web version timed out after ${timeoutMs}ms`)), timeoutMs);
+    timer.unref?.();
+    let onExternalAbort = null;
+    const externalSignal = options.signal;
+    if (externalSignal) {
+        if (externalSignal.aborted) {
+            controller.abort(externalSignal.reason);
+        }
+        else {
+            onExternalAbort = () => controller.abort(externalSignal.reason);
+            externalSignal.addEventListener('abort', onExternalAbort, { once: true });
+        }
+    }
+    try {
+        const headers = {
+            'sec-fetch-site': 'none',
+            'user-agent': options.userAgent ?? DEFAULT_USER_AGENT
+        };
+        if (options.headers) {
+            for (const key in options.headers) {
+                headers[key.toLowerCase()] = options.headers[key];
+            }
+        }
+        const init = {
+            method: 'GET',
+            headers,
+            signal: controller.signal
+        };
+        if (dispatcher) {
+            // dispatcher is a non-standard undici-only extension to RequestInit
+            ;
+            init.dispatcher = dispatcher;
+        }
+        let response;
+        try {
+            response = await fetchImpl(SW_JS_URL, init);
+        }
+        catch (error) {
+            throw new Error(`failed to fetch sw.js: ${toError(error).message}`);
+        }
+        if (!response.ok) {
+            throw new Error(`failed to fetch sw.js: http ${response.status}`);
+        }
+        const body = await response.text();
+        const match = CLIENT_REVISION_PATTERN.exec(body);
+        if (!match?.[1]) {
+            throw new Error('client_revision not found in sw.js response');
+        }
+        const revision = Number.parseInt(match[1], 10);
+        if (!Number.isSafeInteger(revision) || revision <= 0) {
+            throw new Error(`invalid client_revision in sw.js: ${match[1]}`);
+        }
+        return {
+            version: `2.3000.${revision}`,
+            parts: [2, 3000, revision]
+        };
+    }
+    finally {
+        clearTimeout(timer);
+        if (externalSignal && onExternalAbort) {
+            externalSignal.removeEventListener('abort', onExternalAbort);
+        }
+    }
+}

package/dist/esm/util/async.js

@@ -1,3 +1,7 @@
+/**
+ * Returns a Promise that resolves after `ms` milliseconds. Thin wrapper over
+ * `setTimeout` for use in `await` chains.
+ */
 export function delay(ms) {
     return new Promise((resolve) => {
         setTimeout(resolve, ms);

package/dist/esm/util/bytes.js

@@ -62,9 +62,14 @@ export function hexToBytes(value) {
     }
     return out;
 }
+/** Encodes a Uint8Array to a standard padded base64 string. */
 export function bytesToBase64(value) {
     return encodeBase64(value, BASE64_CHARS, true);
 }
+/**
+ * Decodes a standard padded base64 string to a Uint8Array. Throws on invalid
+ * characters or a length that is not a multiple of 4.
+ */
 export function base64ToBytes(value) {
     const len = value.length;
     if (len === 0)
@@ -104,12 +109,17 @@ export function base64ToBytes(value) {
     }
     return out;
 }
-export function base64ToBytesChecked(value, field, requireNonEmpty = true) {
-    if (requireNonEmpty && value.length === 0) {
+export function base64ToBytesChecked(value, field) {
+    if (value.length === 0) {
         throw new Error(`invalid base64 payload for ${field}`);
     }
     return base64ToBytes(value);
 }
+/**
+ * Decodes a base64url-encoded value to a Uint8Array, restoring padding and
+ * the `+`/`/` alphabet first. Throws with a `missing ${field}` message when
+ * `value` is empty/undefined.
+ */
 export function decodeBase64Url(value, field) {
     if (!value) {
         throw new Error(`missing ${field}`);
@@ -189,6 +199,7 @@ function encodeBase64(value, alphabet, pad) {
     }
     return out.join('');
 }
+/** Concatenates an array of Uint8Arrays into a single new Uint8Array. */
 export function concatBytes(parts) {
     let total = 0;
     for (let i = 0; i < parts.length; i += 1) {
@@ -202,6 +213,13 @@ export function concatBytes(parts) {
     }
     return out;
 }
+/**
+ * Returns a zero-copy `Uint8Array` view over the input. Subclasses of
+ * `Uint8Array` (Node `Buffer`) are wrapped in a plain view; `ArrayBuffer`/
+ * `ArrayBufferView` get a view over their backing buffer. Use at system
+ * boundaries (WebCrypto / Node crypto / WebSocket results) – not on values
+ * that are already plain `Uint8Array`.
+ */
 export function toBytesView(value) {
     if (value instanceof Uint8Array) {
         return value.constructor === Uint8Array
@@ -213,6 +231,10 @@ export function toBytesView(value) {
     }
     return new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
 }
+/**
+ * Normalizes an arbitrary stream chunk (string / Uint8Array / ArrayBuffer /
+ * ArrayBufferView) to a Uint8Array. Throws on unsupported types.
+ */
 export function toChunkBytes(chunk) {
     if (typeof chunk === 'string') {
         return TEXT_ENCODER.encode(chunk);
@@ -222,12 +244,20 @@ export function toChunkBytes(chunk) {
     }
     throw new Error(`unsupported stream chunk type: ${typeof chunk}`);
 }
+/**
+ * Constant-time, JIT-resistant equality over `Uint8Array`s. Required for
+ * MAC/HMAC/signature comparisons (use {@link uint8Equal} for non-secret data).
+ */
 export function uint8TimingSafeEqual(left, right) {
     if (left.byteLength !== right.byteLength) {
         return false;
     }
     return timingSafeEqual(left, right);
 }
+/**
+ * XOR-accumulated equality over `Uint8Array`s. Suitable for non-secret data
+ * (e.g. identity key match). Use {@link uint8TimingSafeEqual} for MAC checks.
+ */
 export function uint8Equal(a, b) {
     if (a.length !== b.length) {
         return false;
@@ -270,6 +300,11 @@ export function intToBytes(byteLength, value) {
     }
     return out;
 }
+/**
+ * Drains a Node `Readable` stream into a single Uint8Array. When
+ * `options.maxBytes` is set, the stream is destroyed and the promise rejects
+ * once the limit is exceeded.
+ */
 export async function readAllBytes(stream, options = {}) {
     const maxBytes = options.maxBytes;
     if (maxBytes !== undefined && (!Number.isSafeInteger(maxBytes) || maxBytes < 0)) {

package/dist/esm/util/clock.js

@@ -0,0 +1,15 @@
+export function createServerClock(getClockSkewMs) {
+    return {
+        nowMs() {
+            const skewMs = getClockSkewMs();
+            const nowMs = Date.now();
+            return Number.isFinite(skewMs) ? nowMs + skewMs : nowMs;
+        },
+        nowSeconds() {
+            const skewMs = getClockSkewMs();
+            const nowMs = Date.now();
+            const correctedMs = Number.isFinite(skewMs) ? nowMs + skewMs : nowMs;
+            return Math.floor(correctedMs / 1000);
+        }
+    };
+}

package/dist/esm/util/coercion.js

@@ -1,44 +1,61 @@
 import { toBytesView } from './bytes.js';
 import { toSafeNumber } from './primitives.js';
+/**
+ * Coerces `value` to a safe-integer/finite number, accepting `number` and
+ * `bigint` inputs. Throws with a `${field}`-suffixed message on any other type.
+ */
 export function asNumber(value, field) {
-    if (typeof value === 'bigint') {
-        return toSafeNumber(Number(value), field);
-    }
     if (typeof value === 'number') {
         return toSafeNumber(value, field);
     }
+    if (typeof value === 'bigint') {
+        return toSafeNumber(Number(value), field);
+    }
     throw new Error(`invalid number value for ${field}`);
 }
+/** Optional variant of {@link asNumber}; returns `undefined` when input is nullish. */
 export function asOptionalNumber(value, field = 'optional number') {
     if (value === null || value === undefined)
         return undefined;
     return asNumber(value, field);
 }
+/** Asserts that `value` is a string. Throws with a `${field}`-suffixed message otherwise. */
 export function asString(value, field) {
     if (typeof value === 'string') {
         return value;
     }
     throw new Error(`invalid string value for ${field}`);
 }
+/** Optional variant of {@link asString}; returns `undefined` when input is nullish. */
 export function asOptionalString(value, field = 'optional string') {
     if (value === null || value === undefined)
         return undefined;
     return asString(value, field);
 }
+/**
+ * Coerces `value` to a Uint8Array view, accepting `Uint8Array`, `ArrayBuffer`,
+ * and any `ArrayBufferView`. Throws with a `${field}`-suffixed message otherwise.
+ */
 export function asBytes(value, field) {
     if (value instanceof Uint8Array || value instanceof ArrayBuffer || ArrayBuffer.isView(value)) {
         return toBytesView(value);
     }
     throw new Error(`invalid bytes value for ${field}`);
 }
+/** Optional variant of {@link asBytes}; returns `undefined` when input is nullish. */
 export function asOptionalBytes(value, field = 'optional bytes') {
     if (value === null || value === undefined)
         return undefined;
     return asBytes(value, field);
 }
+/** Returns `undefined` when `value` is nullish, otherwise `Boolean(value)`. */
 export function toBoolOrUndef(value) {
     return value === null || value === undefined ? undefined : Boolean(value);
 }
+/**
+ * Returns `value` when it is a positive safe-integer, `fallback` when it is
+ * undefined, and throws otherwise.
+ */
 export function resolvePositive(value, fallback, name) {
     if (value === undefined)
         return fallback;
@@ -46,3 +63,28 @@ export function resolvePositive(value, fallback, name) {
         return value;
     throw new Error(`${name} must be a positive safe integer`);
 }
+/**
+ * Lenient variants for parsing external JSON payloads (GraphQL responses,
+ * Mex notifications) where fields may be missing, empty, or arrive as the
+ * wrong primitive. Return null instead of throwing.
+ */
+export function tryAsString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : null;
+}
+export function tryAsNumber(value) {
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (typeof value === 'string') {
+        const normalized = value.trim();
+        if (normalized.length === 0)
+            return null;
+        const parsed = Number(normalized);
+        return Number.isFinite(parsed) ? parsed : null;
+    }
+    return null;
+}
+export function tryAsRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}