Add RawNodeHandler hook and DisabledFeatures policy

Adds two opt-in extension points for proxy/intermediary use cases:

1. `Client.RawNodeHandler` — called for every inbound node after Noise
   decrypt + Node decode, before standard dispatch (IQ response match,
   tag-based routing). Handlers can drop the node, replace it with a
   modified copy, or pass through. Lets an external system observe or
   take over inbound stanza handling without forking the library.

2. `Client.DisabledFeatures.Signal` — short-circuits the library's
   Signal session machinery: decryptMessages becomes a true no-op (no
   decrypt and no ack — the downstream decrypting client is responsible
   for ack'ing), uploadPreKeys becomes a no-op. Use when an external
   system owns the Signal session for this device.

Both are labeled DANGEROUS in their godoc: incorrect use breaks
stateful invariants (session ratchets, IQ correlation, etc.). They
exist to let upstream services hold the Signal session externally and
forward raw envelopes verbatim, without the library second-guessing.

Designed as forward-compatible additions:
  - DisabledFeatures is a struct so future flags add fields rather
    than parameters.
  - RawNodeHandler returns (modified, drop) so the contract can grow
    without changing the signature.

Zero behavior change when the new fields are left at their zero values.

Author: purpshell

client.go

@@ -46,6 +46,41 @@ type EventHandler func(evt any)
 type EventHandlerWithSuccessStatus func(evt any) bool
 type nodeHandler func(ctx context.Context, node *waBinary.Node)
 
+// RawNodeHandler is called for every inbound stanza node after Noise
+// transport decryption and binary decoding, but before standard
+// dispatch (tag-based routing, IQ response correlation).
+//
+// If the handler returns drop=true, the node is not dispatched further
+// (no tag handler runs, no IQ response is matched). If the handler
+// returns a non-nil modified node, it replaces the original for the
+// rest of the dispatch path.
+//
+// DANGEROUS: this is a low-level hook. Returning incorrect values
+// breaks Signal session continuity, IQ response correlation, app state
+// invariants, and other stateful parts of the protocol. Intended for
+// proxy implementations where an external system owns part of the
+// protocol state machine (see also [DisabledFeatures]).
+type RawNodeHandler func(ctx context.Context, node *waBinary.Node) (modified *waBinary.Node, drop bool)
+
+// DisabledFeatures lets callers turn off built-in whatsmeow processing
+// paths. Used by proxies where an external system owns parts of the
+// protocol state, e.g. an upstream service that holds the Signal
+// session and handles its own decryption.
+//
+// DANGEROUS: each flag disables a piece of state machinery the rest of
+// the library assumes is running. Toggle deliberately; the surrounding
+// code does not paper over the resulting gaps.
+type DisabledFeatures struct {
+	// Signal disables the library's Signal-session machinery. When set:
+	//   - Incoming `<message>` envelopes are not decrypted and not
+	//     ack'd. The actual decrypting client downstream is responsible
+	//     for ack'ing once it has processed the message.
+	//   - The periodic prekey-upload loop is a no-op.
+	// Combine with [RawNodeHandler] to forward the raw envelopes to the
+	// system that actually owns the Signal session.
+	Signal bool
+}
+
 var nextHandlerID uint32
 
 type wrappedEventHandler struct {
@@ -177,6 +212,14 @@ type Client struct {
 	// If false, decrypting a message from untrusted devices will fail.
 	AutoTrustIdentity bool
 
+	// RawNodeHandler, if non-nil, is called for every inbound node
+	// after decoding but before standard dispatch. See [RawNodeHandler].
+	RawNodeHandler RawNodeHandler
+
+	// DisabledFeatures controls which built-in processing paths are
+	// skipped. See [DisabledFeatures].
+	DisabledFeatures DisabledFeatures
+
 	// Should SubscribePresence return an error if no privacy token is stored for the user?
 	ErrorOnSubscribePresenceWithoutToken bool
 
@@ -826,6 +869,16 @@ func (cli *Client) handleFrame(ctx context.Context, data []byte) {
 		cli.Log.Debugf("Errored frame hex: %s", hex.EncodeToString(decompressed))
 		return
 	}
+	if h := cli.RawNodeHandler; h != nil {
+		modified, drop := h(ctx, node)
+		if drop {
+			cli.recvLog.Debugf("RawNodeHandler dropped node: %s", node.XMLString())
+			return
+		}
+		if modified != nil {
+			node = modified
+		}
+	}
 	cli.recvLog.Debugf("%s", node.XMLString())
 	if node.Tag == "xmlstreamend" {
 		if !cli.isExpectedDisconnect() {

message.go

@@ -60,6 +60,11 @@ func (cli *Client) handleEncryptedMessage(ctx context.Context, node *waBinary.No
 			var cancelled bool
 			defer cli.maybeDeferredAck(ctx, node)(&cancelled)
 			cancelled = cli.handlePlaintextMessage(ctx, info, node)
+		} else if cli.DisabledFeatures.Signal {
+			// External system owns the Signal session. We do not decrypt
+			// and we do not ack: the actual decrypting client downstream
+			// is responsible for ack'ing once it has received and
+			// processed the message.
 		} else {
 			cli.decryptMessages(ctx, info, node)
 		}

prekeys.go

@@ -48,6 +48,10 @@ func (cli *Client) getServerPreKeyCount(ctx context.Context) (int, error) {
 }
 
 func (cli *Client) uploadPreKeys(ctx context.Context, initialUpload bool) {
+	if cli.DisabledFeatures.Signal {
+		cli.Log.Debugf("Prekey upload skipped (DisabledFeatures.Signal)")
+		return
+	}
 	cli.uploadPreKeysLock.Lock()
 	defer cli.uploadPreKeysLock.Unlock()
 	if cli.lastPreKeyUpload.Add(10 * time.Minute).After(time.Now()) {