[v1.2] Better SDK diagnostics on signature failure

[MaxMansfield]

Context

When HMAC signature verification fails today, the SDK silently returns false and the developer has no information about why the mismatch happened. Common causes:

• Wrong secret pasted into env (most common)
• Trailing newline / extra quotes in the secret value
• Timestamp drift (clock skew > Zoom's tolerance)
• Body encoding mismatch (the DEVS-X1 canonical-JSON issue)

Cost-of-debug for the AWS Terraform deploy on 2026-05-20: ~90 minutes. Once we added diagnostic logging (computed sig vs expected, secret length + prefix/suffix, body length, timestamp delta) the actual bug — wrong secret — surfaced in 30 seconds.

What to ship

A "diagnostic" mode controlled by an env var or constructor parameter:

ZM_RTMS_DEBUG_SIGNATURES=true

When enabled, every failed verify_webhook_signature() call logs (at WARN level):

• Computed signature (full)
• Expected signature from header (full)
• Body length (bytes)
• Body first 100 + last 100 chars
• Timestamp from header + current time + delta in seconds
• Secret length + first 2 chars + last 2 chars (NEVER the full secret)

When disabled (default), failures are logged as a single WARN line with no details.

Acceptance criteria

• ZM_RTMS_DEBUG_SIGNATURES env var supported in both Python and Node
• Diagnostic output includes the 6 fields above
• Secret value is never logged in full — only length + first/last 2 chars
• Test with a deliberately-wrong secret confirms the diagnostic surfaces the mismatch

Cross-language parity

• Python implementation
• Node.js implementation
• Same env var name and behavior
• Same redaction rules for the secret value

Source

Tracked in vault: Projects/RTMS SDK v1.2.md → DEVS-X5.

Tracker

Part of the v1.2 milestone. Project: https://github.com/orgs/zoom/projects/11.