What it is
A utility module that provides cryptographic primitives and webhook signature verification for use inside a SpacetimeDB server module. It covers hashing, HMAC signing, encoding conversions, and ready-made verifiers for common webhook providers.
Where it fits
- Webhook ingestion: An app that receives webhooks from Stripe, GitHub, or Resend needs to authenticate each request before trusting its payload.
- Secrets management: A module that stores API keys or webhook secrets in private tables and needs to sign or verify data without exposing those secrets to clients.
- Custom HMAC workflows: A game or app backend that issues signed tokens or verifies signed messages between services can use the hashing and HMAC primitives directly.
- Encoding interop: A module that exchanges data with external systems using hex or base64 representations needs reliable, strict conversion that rejects malformed input.
- Replay attack prevention: Any handler that must reject requests with stale or missing timestamps can use the built-in tolerance checking included in each webhook verifier.
How it works
The module centers on two layers. The lower layer provides general-purpose building blocks: producing a hash digest from arbitrary data, producing an HMAC signature given a secret and a message, and converting between raw bytes and common text encodings. These primitives can be composed freely for any signing or verification need your module has.
The upper layer wraps those primitives into verifiers tailored to specific webhook providers. Each verifier takes the raw request body, the signature header sent by the provider, your stored secret, and the current server timestamp. It reconstructs the expected signature, compares it against the one in the header using a byte-by-byte comparison that does not short-circuit early, and checks that the timestamp falls within an acceptable window. The result is a simple pass or fail value with a reason code, so your handler can reject bad requests before doing any further processing.
Because the verifiers rely on the module's own server timestamp rather than a client-supplied value, replay window enforcement stays consistent regardless of client clock drift. Secrets are expected to live in private tables, keeping them out of any data visible to connected clients.
