wscall-client 0.3.0 → 0.4.0

package/README.md

@@ -9,6 +9,7 @@ Works in both **Node.js** (≥18) and modern **browsers** (native WebSocket + We
 - **Protocol v3 binary codec** — compact 5-byte frame header, single-letter JSON keys, raw binary attachments (zero Base64 overhead).
 - **Encryption** — ChaCha20-Poly1305 and AES-256-GCM at frame level; no TLS required.
 - **ECDH key agreement** — X25519 dynamic per-connection session key (forward secrecy), no pre-shared key needed.
+- **Connection authentication** — submit a credential (e.g. token) during the handshake; rejected connections fail fast at `connect` time (requires server ≥ 0.6.0).
 - **Bidirectional messaging** — request/response RPC + server-pushed events with ACK correlation.
 - **Automatic reconnect** — exponential backoff with jitter; sticky failover across multiple server URLs.
 - **Zero-copy attachments** — send and receive binary files inline with RPC params or event data.
@@ -39,9 +40,9 @@ const client = await WscallClient.connect(
   WscallClientConfig.ecdh()
 );
 
-// RPC call
+// RPC call (resolves directly with the response data)
 const res = await client.call('system.echo', { message: 'hello' });
-console.log(res.data); // { message: 'hello' }
+console.log(res); // { message: 'hello' }
 
 // Subscribe to server events
 client.onEvent('chat.message', (event) => {
@@ -49,9 +50,9 @@ client.onEvent('chat.message', (event) => {
   return { received: true }; // sent back as ACK receipt
 });
 
-// Emit an event (with ACK)
-const ack = await client.sendEvent('chat.message', { text: 'hi!' });
-console.log('Server acknowledged:', ack.receipt);
+// Emit an event (resolves with the ACK receipt)
+const receipt = await client.sendEvent('chat.message', { text: 'hi!' });
+console.log('Server acknowledged:', receipt);
 
 client.close();
 ```
@@ -79,6 +80,19 @@ const client = await WscallClient.connect('ws://primary:9001/socket', config);
 
 On disconnect the client iterates through `[primary, ...failover]` starting from the last successfully connected URL (sticky failover).
 
+### Authenticated connection (server ≥ 0.6.0)
+
+When the server registers an `auth_handler`, submit your credential at connect time. The credential is sent as an encrypted frame right after key agreement — no tokens in URLs or HTTP headers.
+
+```js
+const client = await WscallClient.connect(
+  'ws://127.0.0.1:9001/socket',
+  WscallClientConfig.ecdh().withCredential('my-token')
+);
+```
+
+If the server rejects the credential, `connect` rejects with a `ClientError` whose `code` is the server error code (e.g. `unauthorized`) and whose `details` carries the full error payload.
+
 ### File attachments
 
 ```js
@@ -108,17 +122,23 @@ Static factory. Connects to a WSCALL server and returns a ready client.
 | `WscallClientConfig.pskChaCha20(key)` | PSK with ChaCha20-Poly1305 |
 | `WscallClientConfig.pskAes256(key)` | PSK with AES-256-GCM |
 | `.withAutoReconnect(bool)` | Enable/disable auto-reconnect |
-| `.withTimeout(ms)` | Default request timeout |
+| `.withTimeout(ms)` | Default request timeout (default 10s). Raise it for long-running workloads, or pass a per-call `options.timeout` |
+| `.withHeartbeatInterval(ms)` | Keep-alive ping interval (default 15s) |
+| `.withIdleTimeout(ms)` | Inbound idle timeout (default 45s) |
+| `.withReconnectBaseDelay(ms)` | Reconnect backoff base delay (default 3s) |
+| `.withReconnectMaxDelay(ms)` | Reconnect backoff upper bound (default 30s) |
+| `.withAuthTimeout(ms)` | Auth handshake timeout (default 10s) |
 | `.withMetadata(obj)` | Default metadata sent with requests |
 | `.withFailoverUrl(url)` | Append a failover URL |
 | `.withFailoverUrls(urls)` | Set all failover URLs |
+| `.withCredential(credential)` | Credential (token) for the auth handshake |
 
 ### `client`
 
 | Method | Description |
 |--------|-------------|
-| `call(route, params?, attachments?, opts?)` | RPC call → `Promise<ApiResponse>` |
-| `sendEvent(name, data?, attachments?, opts?)` | Emit event → `Promise<EventAck>` |
+| `call(route, params?, attachments?, opts?)` | RPC call → `Promise<data>` (response data directly) |
+| `sendEvent(name, data?, attachments?, opts?)` | Emit event → `Promise<receipt>` (ACK receipt) |
 | `onEvent(name, handler)` | Subscribe to server events |
 | `offEvent(name, handler?)` | Unsubscribe |
 | `onConnected(handler)` | Connection established hook |
@@ -128,18 +148,19 @@ Static factory. Connects to a WSCALL server and returns a ready client.
 ### Reconnect behavior
 
 1. Unexpected disconnects trigger automatic reconnect (default: enabled).
-2. First retry after 3 s, then exponential backoff (×2), capped at 30 s.
+2. First retry after 3 s (`reconnectBaseDelayMs`), then exponential backoff (×2), capped at 30 s (`reconnectMaxDelayMs`).
 3. Random sub-second jitter prevents thundering-herd storms.
 4. With `failoverUrls`, each cycle tries all URLs before applying backoff.
 5. `close()` stops all reconnect attempts.
 
 ## Protocol Compatibility
 
-This SDK implements **WSCALL Protocol v3** (5-byte frame header, connection-level encryption). It requires a server running `wscall` ≥ 0.5.1.
+This SDK implements **WSCALL Protocol v3** (5-byte frame header, connection-level encryption). It requires a server running `wscall` ≥ 0.5.1; the credential handshake (`withCredential`) requires server ≥ 0.6.0.
 
 | SDK version | Protocol | Server compatibility |
 |-------------|----------|---------------------|
-| 0.3.x | v3 | wscall ≥ 0.5.1 |
+| 0.4.x | v3 | wscall ≥ 0.5.1 (auth: ≥ 0.6.0; timing knobs pair best with server ≥ 0.7.0) |
+| 0.3.x | v3 | wscall ≥ 0.5.1 (auth: ≥ 0.6.0) |
 | 0.2.x | v2 | wscall 0.4.x – 0.5.0 |
 
 ## Browser Usage
@@ -150,7 +171,7 @@ This SDK implements **WSCALL Protocol v3** (5-byte frame header, connection-leve
 
   const client = await WscallClient.connect('ws://localhost:9001/socket', WscallClientConfig.ecdh());
   const res = await client.call('system.echo', { msg: 'from browser' });
-  console.log(res.data);
+  console.log(res);
 </script>
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wscall-client",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "High-performance JavaScript client SDK for the WSCALL WebSocket RPC framework",
   "type": "module",
   "main": "./src/index.js",

package/src/client.js

@@ -18,9 +18,11 @@ import {
   K_API_RESPONSE,
   K_EVENT_EMIT,
   K_EVENT_ACK,
+  K_AUTH_RESPONSE,
   buildApiRequest,
   buildEventEmit,
   buildEventAck,
+  buildAuthRequest,
   ProtocolError,
   generateEcdhKeypair,
   parsePeerPublic,
@@ -34,6 +36,8 @@ const IDLE_TIMEOUT_MS = 45_000;
 const DEFAULT_TIMEOUT_MS = 10_000;
 const RECONNECT_BASE_DELAY_MS = 3_000;
 const RECONNECT_MAX_DELAY_MS = 30_000;
+/** Timeout for the auth handshake (AuthRequest -> AuthResponse). */
+const AUTH_TIMEOUT_MS = 10_000;
 
 // ─── Errors ───────────────────────────────────────────────────────────────────
 
@@ -64,6 +68,14 @@ export class ClientError extends Error {
       errorPayload
     );
   }
+
+  static authFailed(errorPayload) {
+    return new ClientError(
+      errorPayload?.message || 'Authentication failed',
+      errorPayload?.code || 'AUTH_FAILED',
+      errorPayload
+    );
+  }
 }
 
 // ─── Pending Request Tracker ──────────────────────────────────────────────────
@@ -159,12 +171,29 @@ export class WscallClientConfig {
   useEcdh = true;
   /** @type {boolean} Auto reconnect on unexpected disconnect */
   autoReconnect = true;
-  /** @type {number} Default request timeout (ms) */
+  /** @type {number} Default request timeout (ms). Long-running workloads
+   * (large file transfers, heavy computation, big database queries) routinely
+   * exceed the 10s default; raise this or pass a per-call `options.timeout`. */
   timeout = DEFAULT_TIMEOUT_MS;
+  /** @type {number} Keep-alive ping interval (ms). Must stay well below
+   * `idleTimeoutMs` and the server's idle timeout. */
+  heartbeatIntervalMs = HEARTBEAT_INTERVAL_MS;
+  /** @type {number} Drop the connection when no inbound frame arrives within
+   * this window (ms). */
+  idleTimeoutMs = IDLE_TIMEOUT_MS;
+  /** @type {number} Reconnect exponential backoff base delay (ms) */
+  reconnectBaseDelayMs = RECONNECT_BASE_DELAY_MS;
+  /** @type {number} Reconnect exponential backoff upper bound (ms) */
+  reconnectMaxDelayMs = RECONNECT_MAX_DELAY_MS;
+  /** @type {number} Auth handshake (AuthRequest -> AuthResponse) timeout (ms) */
+  authTimeoutMs = AUTH_TIMEOUT_MS;
   /** @type {object} Default metadata sent with requests */
   metadata = {};
   /** @type {string[]} Failover server URLs tried when the primary is unreachable */
   failoverUrls = [];
+  /** @type {string|null} Credential (e.g. token) submitted during the auth
+   * handshake. Leave null when the server does not require authentication. */
+  credential = null;
 
   /** Creates a config with the recommended secure defaults (ECDH + ChaCha20 + auto-reconnect). */
   static default() {
@@ -205,6 +234,16 @@ export class WscallClientConfig {
   withAutoReconnect(v) { this.autoReconnect = v; return this; }
   /** Builder: set default timeout (ms). */
   withTimeout(ms) { this.timeout = ms; return this; }
+  /** Builder: set keep-alive ping interval (ms). */
+  withHeartbeatInterval(ms) { this.heartbeatIntervalMs = ms; return this; }
+  /** Builder: set inbound idle timeout (ms). */
+  withIdleTimeout(ms) { this.idleTimeoutMs = ms; return this; }
+  /** Builder: set reconnect backoff base delay (ms). */
+  withReconnectBaseDelay(ms) { this.reconnectBaseDelayMs = ms; return this; }
+  /** Builder: set reconnect backoff upper bound (ms). */
+  withReconnectMaxDelay(ms) { this.reconnectMaxDelayMs = ms; return this; }
+  /** Builder: set auth handshake timeout (ms). */
+  withAuthTimeout(ms) { this.authTimeoutMs = ms; return this; }
   /** Builder: set default metadata. */
   withMetadata(meta) { this.metadata = meta; return this; }
   /** Builder: set a pre-shared ChaCha20 key (disables ECDH). */
@@ -215,6 +254,9 @@ export class WscallClientConfig {
   withFailoverUrl(url) { this.failoverUrls.push(url); return this; }
   /** Builder: set the full failover URL list (replaces any previously added). */
   withFailoverUrls(urls) { this.failoverUrls = [...urls]; return this; }
+  /** Builder: set the credential (token) submitted during the auth handshake.
+   * Authentication failures surface as AUTH_FAILED errors from `connect`. */
+  withCredential(credential) { this.credential = credential; return this; }
 }
 
 // ─── WscallClient ─────────────────────────────────────────────────────────────
@@ -228,8 +270,15 @@ export class WscallClient {
   #defaultEncryption;
   #autoReconnect;
   #defaultTimeout;
+  #heartbeatIntervalMs;
+  #idleTimeoutMs;
+  #reconnectBaseDelayMs;
+  #reconnectMaxDelayMs;
+  #authTimeoutMs;
   #metadata;
   #useEcdh = false;
+  /** @type {string|null} Credential submitted during the auth handshake */
+  #credential = null;
 
   // Connection state
   #ws = null;
@@ -265,18 +314,51 @@ export class WscallClient {
    * @param {boolean} [options.useEcdh=false] - Use ECDH dynamic key agreement
    * @param {boolean} [options.autoReconnect=true] - Auto reconnect on disconnect
    * @param {number} [options.timeout=10000] - Default request timeout (ms)
+   * @param {number} [options.heartbeatIntervalMs=15000] - Keep-alive ping interval (ms)
+   * @param {number} [options.idleTimeoutMs=45000] - Inbound idle timeout (ms)
+   * @param {number} [options.reconnectBaseDelayMs=3000] - Reconnect backoff base delay (ms)
+   * @param {number} [options.reconnectMaxDelayMs=30000] - Reconnect backoff upper bound (ms)
+   * @param {number} [options.authTimeoutMs=10000] - Auth handshake timeout (ms)
    * @param {object} [options.metadata] - Default metadata sent with requests
+   * @param {string} [options.credential] - Credential for the auth handshake
    */
   constructor(options = {}) {
-    const { url, failoverUrls = [], chacha20Key, aes256Key, useEcdh = false, autoReconnect = true, timeout = DEFAULT_TIMEOUT_MS, metadata = {} } = options;
+    const {
+      url,
+      failoverUrls = [],
+      chacha20Key,
+      aes256Key,
+      useEcdh = false,
+      autoReconnect = true,
+      timeout = DEFAULT_TIMEOUT_MS,
+      heartbeatIntervalMs = HEARTBEAT_INTERVAL_MS,
+      idleTimeoutMs = IDLE_TIMEOUT_MS,
+      reconnectBaseDelayMs = RECONNECT_BASE_DELAY_MS,
+      reconnectMaxDelayMs = RECONNECT_MAX_DELAY_MS,
+      authTimeoutMs = AUTH_TIMEOUT_MS,
+      metadata = {},
+      credential = null,
+    } = options;
 
     if (!url) throw new Error('url is required');
 
+    // Normalize timing knobs: non-finite values fall back to the defaults,
+    // non-positive values are clamped to 1ms so timers fire and reconnect
+    // backoff never degenerates into a busy loop.
+    const positiveMs = (v, fallback) =>
+      Number.isFinite(v) ? Math.max(1, v) : fallback;
+
     this.#urls = [url, ...failoverUrls];
     this.#autoReconnect = autoReconnect;
-    this.#defaultTimeout = timeout;
+    this.#defaultTimeout = positiveMs(timeout, DEFAULT_TIMEOUT_MS);
+    this.#heartbeatIntervalMs = positiveMs(heartbeatIntervalMs, HEARTBEAT_INTERVAL_MS);
+    this.#idleTimeoutMs = positiveMs(idleTimeoutMs, IDLE_TIMEOUT_MS);
+    this.#reconnectBaseDelayMs = positiveMs(reconnectBaseDelayMs, RECONNECT_BASE_DELAY_MS);
+    this.#reconnectMaxDelayMs = positiveMs(reconnectMaxDelayMs, RECONNECT_MAX_DELAY_MS);
+    this.#authTimeoutMs = positiveMs(authTimeoutMs, AUTH_TIMEOUT_MS);
     this.#metadata = metadata;
     this.#useEcdh = useEcdh;
+    this.#credential = credential;
 
     this.#codec = new FrameCodec();
     if (useEcdh) {
@@ -316,7 +398,13 @@ export class WscallClient {
         useEcdh: config.useEcdh,
         autoReconnect: config.autoReconnect,
         timeout: config.timeout,
+        heartbeatIntervalMs: config.heartbeatIntervalMs,
+        idleTimeoutMs: config.idleTimeoutMs,
+        reconnectBaseDelayMs: config.reconnectBaseDelayMs,
+        reconnectMaxDelayMs: config.reconnectMaxDelayMs,
+        authTimeoutMs: config.authTimeoutMs,
         metadata: config.metadata,
+        credential: config.credential,
       };
     } else {
       options = { url, ...config };
@@ -555,6 +643,10 @@ export class WscallClient {
       // buffered here and replayed once the session key is ready.
       let handshakeBuffer = [];
 
+      // Auth handshake state (optional, only when a credential is configured).
+      let authPending = false;
+      let authTimer = null;
+
       const completeConnection = () => {
         this.#connected = true;
         this.#reconnectAttempt = 0;
@@ -573,6 +665,32 @@ export class WscallClient {
         }
       };
 
+      // Auth phase: if a credential is configured, send an AuthRequest frame
+      // (encrypted with the session key in ECDH mode) and wait for the
+      // AuthResponse before marking the connection ready.
+      const startAuthOrComplete = () => {
+        if (!this.#credential) {
+          completeConnection();
+          return;
+        }
+        authPending = true;
+        authTimer = setTimeout(() => {
+          if (!authPending) return;
+          authPending = false;
+          reject(new ClientError('Auth handshake timed out', 'AUTH_TIMEOUT'));
+          try { ws.close(); } catch { /* ignore */ }
+        }, this.#authTimeoutMs);
+        if (authTimer.unref) authTimer.unref();
+        this.#codec
+          .encode(buildAuthRequest(this.#credential))
+          .then((frame) => ws.send(frame))
+          .catch((err) => {
+            authPending = false;
+            clearTimeout(authTimer);
+            reject(new ClientError(`Failed to send auth frame: ${err.message}`, 'AUTH_ERROR'));
+          });
+      };
+
       const onOpenAsync = async () => {
         if (this.#generation !== generation) return;
 
@@ -588,7 +706,7 @@ export class WscallClient {
             reject(new ClientError(`ECDH keypair generation failed: ${err.message}`, 'ECDH_ERROR'));
           }
         } else {
-          completeConnection();
+          startAuthOrComplete();
         }
       };
 
@@ -633,7 +751,7 @@ export class WscallClient {
                 this.#codec.withChaCha20Key(sessionKey);
                 this.#defaultEncryption = EncryptionKind.ChaCha20;
                 handshakePending = false;
-                completeConnection();
+                startAuthOrComplete();
               })
               .catch((err) => {
                 reject(new ClientError(
@@ -652,6 +770,35 @@ export class WscallClient {
           return;
         }
 
+        if (authPending) {
+          // Expect an AuthResponse frame; any other frame is buffered and
+          // replayed after the auth handshake completes.
+          this.#codec
+            .decode(data)
+            .then(({ body }) => {
+              if (!authPending) return;
+              if (body.k !== K_AUTH_RESPONSE) {
+                handshakeBuffer.push(data);
+                return;
+              }
+              authPending = false;
+              clearTimeout(authTimer);
+              if (body.o) {
+                completeConnection();
+              } else {
+                reject(ClientError.authFailed(body.er));
+                try { ws.close(); } catch { /* ignore */ }
+              }
+            })
+            .catch((err) => {
+              if (!authPending) return;
+              authPending = false;
+              clearTimeout(authTimer);
+              reject(new ClientError(`Auth handshake failed: ${err.message}`, 'AUTH_ERROR'));
+            });
+          return;
+        }
+
         this.#resetIdleTimer();
         this.#handleInbound(data);
       };
@@ -725,11 +872,14 @@ export class WscallClient {
 
   #reconnectDelay(attempt) {
     const exp = Math.min(Math.max(attempt, 1) - 1, 6);
-    return Math.min(RECONNECT_BASE_DELAY_MS * (1 << exp), RECONNECT_MAX_DELAY_MS);
+    return Math.min(
+      this.#reconnectBaseDelayMs * (1 << exp),
+      this.#reconnectMaxDelayMs,
+    );
   }
 
   #reconnectJitter() {
-    return Math.random() * (RECONNECT_BASE_DELAY_MS / 2);
+    return Math.random() * (this.#reconnectBaseDelayMs / 2);
   }
 
   // ─── Internal: Heartbeat & Idle ─────────────────────────────────────────────
@@ -747,7 +897,7 @@ export class WscallClient {
           // For browser, we rely on the idle timeout mechanism.
         }
       } catch { /* connection may have closed */ }
-    }, HEARTBEAT_INTERVAL_MS);
+    }, this.#heartbeatIntervalMs);
 
     if (this.#heartbeatTimer.unref) this.#heartbeatTimer.unref();
   }
@@ -761,7 +911,7 @@ export class WscallClient {
           try { this.#ws.close(4000, 'idle timeout'); } catch { /* ignore */ }
         }
       }
-    }, IDLE_TIMEOUT_MS);
+    }, this.#idleTimeoutMs);
 
     if (this.#idleTimer.unref) this.#idleTimer.unref();
   }

package/src/index.js

@@ -34,11 +34,14 @@ export {
   K_EVENT_EMIT,
   K_API_RESPONSE,
   K_EVENT_ACK,
+  K_AUTH_REQUEST,
+  K_AUTH_RESPONSE,
   ECDH_DOMAIN_TAG,
   ECDH_KEY_LEN,
   buildApiRequest,
   buildEventEmit,
   buildEventAck,
+  buildAuthRequest,
   createAttachment,
   createTextAttachment,
   createBytesAttachment,

package/src/protocol.js

@@ -19,21 +19,25 @@
  * │ id_len:u8 │ id │ name_len:u8 │ name │ ct_len:u8 │ content_type │ data_len:u32(be) │ raw_data │
  *
  * JSON body uses compact single-letter keys with a numeric `k` discriminator:
- *   k=0 ApiRequest:  { k, i, r, p, m }
- *   k=1 EventEmit:   { k, i, n, d, m, e }
- *   k=2 ApiResponse: { k, i, o, s, d, er?, m }
- *   k=3 EventAck:    { k, i, o, rc, er? }
+ *   k=0 ApiRequest:   { k, i, r, p, m }
+ *   k=1 EventEmit:    { k, i, n, d, m, e }
+ *   k=2 ApiResponse:  { k, i, o, s, d, er?, m }
+ *   k=3 EventAck:     { k, i, o, rc, er? }
+ *   k=4 AuthRequest:  { k, c }
+ *   k=5 AuthResponse: { k, o, st?, er? }
  */
 
 // ─── Constants ────────────────────────────────────────────────────────────────
 
-export const MessageType = Object.freeze({ Api: 0x00, Event: 0x01 });
+export const MessageType = Object.freeze({ Api: 0x00, Event: 0x01, Auth: 0x02 });
 export const EncryptionKind = Object.freeze({ None: 0x00, ChaCha20: 0x01, Aes256: 0x02 });
 
 export const K_API_REQUEST = 0;
 export const K_EVENT_EMIT = 1;
 export const K_API_RESPONSE = 2;
 export const K_EVENT_ACK = 3;
+export const K_AUTH_REQUEST = 4;
+export const K_AUTH_RESPONSE = 5;
 
 // ─── ECDH Constants ──────────────────────────────────────────────────────────
 
@@ -179,7 +183,7 @@ export class FrameCodec {
     let payload;
     switch (encryption) {
       case EncryptionKind.ChaCha20:
-        payload = this.#encryptChaCha20(composite);
+        payload = await this.#encryptChaCha20(composite);
         break;
       case EncryptionKind.Aes256:
         payload = await this.#encryptAes256(composite);
@@ -234,7 +238,7 @@ export class FrameCodec {
         composite = encryptedPayload;
         break;
       case EncryptionKind.ChaCha20:
-        composite = this.#decryptChaCha20(encryptedPayload);
+        composite = await this.#decryptChaCha20(encryptedPayload);
         break;
       case EncryptionKind.Aes256:
         composite = await this.#decryptAes256(encryptedPayload);
@@ -274,12 +278,12 @@ export class FrameCodec {
 
   // ─── ChaCha20-Poly1305 (uses @noble/ciphers) ──────────────────────────────
 
-  #encryptChaCha20(plaintext) {
+  async #encryptChaCha20(plaintext) {
     // NOTE: chacha20poly1305(key, nonce) is constructed per frame by design —
     // the AEAD requires a fresh nonce each call and @noble/ciphers exposes no
     // safe cross-frame key-schedule cache, so there is nothing to hoist here.
     if (!this.#chacha20Key) throw new ProtocolError('Missing ChaCha20 key');
-    const { chacha20poly1305 } = getCiphers();
+    const { chacha20poly1305 } = await getCiphers();
     const nonce = crypto.getRandomValues(new Uint8Array(NONCE_LEN));
     const cipher = chacha20poly1305(this.#chacha20Key, nonce);
     const ciphertext = cipher.encrypt(plaintext);
@@ -290,10 +294,10 @@ export class FrameCodec {
     return result;
   }
 
-  #decryptChaCha20(payload) {
+  async #decryptChaCha20(payload) {
     if (!this.#chacha20Key) throw new ProtocolError('Missing ChaCha20 key');
     if (payload.length < NONCE_LEN) throw new ProtocolError('Encrypted payload too short for ChaCha20');
-    const { chacha20poly1305 } = getCiphers();
+    const { chacha20poly1305 } = await getCiphers();
     const nonce = payload.subarray(0, NONCE_LEN);
     const ciphertext = payload.subarray(NONCE_LEN);
     const cipher = chacha20poly1305(this.#chacha20Key, nonce);
@@ -332,6 +336,7 @@ function messageTypeForBody(body) {
   const k = body.k;
   if (k === K_API_REQUEST || k === K_API_RESPONSE) return MessageType.Api;
   if (k === K_EVENT_EMIT || k === K_EVENT_ACK) return MessageType.Event;
+  if (k === K_AUTH_REQUEST || k === K_AUTH_RESPONSE) return MessageType.Auth;
   throw new ProtocolError(`Unknown packet kind: ${k}`);
 }
 
@@ -387,26 +392,31 @@ function decodeAttachmentWire(buf, offset) {
   return [{ id, name, content_type, data }, pos];
 }
 
-// Lazy-load @noble/ciphers to keep it optional
-let _ciphers = null;
-function getCiphers() {
-  if (!_ciphers) {
-    try {
-      // Dynamic import won't work synchronously; use createRequire pattern
-      // In practice this is loaded at module init via the top-level import
-      _ciphers = globalThis.__wscall_ciphers;
-    } catch { /* ignore */ }
-  }
-  if (!_ciphers) {
-    throw new ProtocolError(
-      'ChaCha20-Poly1305 requires @noble/ciphers. Install it: npm i @noble/ciphers'
-    );
+// Lazy-load @noble/ciphers' ChaCha20 backend.
+// A backend explicitly injected via `initCiphers()` takes precedence;
+// otherwise the module is imported dynamically on first use (it is a regular
+// dependency of this package, so this succeeds out of the box in Node and
+// bundlers — no manual initCiphers call required).
+let _ciphersPromise = null;
+async function getCiphers() {
+  if (globalThis.__wscall_ciphers) return globalThis.__wscall_ciphers;
+  if (!_ciphersPromise) {
+    // NOTE: @noble/ciphers' root entry throws on import ("import submodules
+    // instead"), so the `chacha` submodule is imported explicitly.
+    _ciphersPromise = import('@noble/ciphers/chacha').catch((err) => {
+      _ciphersPromise = null;
+      throw new ProtocolError(
+        `ChaCha20-Poly1305 requires @noble/ciphers. Install it: npm i @noble/ciphers (${err.message})`
+      );
+    });
   }
-  return _ciphers;
+  return _ciphersPromise;
 }
 
 /**
- * Initialize the cipher backend. Called automatically by WscallClient.
+ * Initialize the cipher backend explicitly (e.g. to use a custom or bundled
+ * implementation). Optional: by default @noble/ciphers is loaded
+ * automatically on first encrypted frame.
  * @param {{ chacha20poly1305: Function }} ciphers
  */
 export function initCiphers(ciphers) {
@@ -438,6 +448,11 @@ export function buildEventAck(eventId, ok = true, receipt = {}, error = undefine
   return body;
 }
 
+/** Build an AuthRequest packet body (sent during the connection handshake). */
+export function buildAuthRequest(credential) {
+  return { k: K_AUTH_REQUEST, c: credential };
+}
+
 /**
  * Create a file attachment object (raw binary, protocol v3).
  * @param {string} id - Attachment identifier