What it is
A utility submodule for server-side cryptographic operations inside a SpacetimeDB module, covering hashing, signature creation, webhook verification, and encoding conversions.
Where it fits
- Incoming webhooks: A module that receives events from Stripe, GitHub, or Resend needs to verify that each request genuinely came from that provider before acting on it.
- Custom HMAC signing: An app that issues signed tokens or authenticates inter-service calls needs to produce and compare message signatures without pulling in a larger library.
- Encoding normalization: A module ingesting data from external APIs that mix hex and base64 representations needs reliable conversion that rejects malformed input.
- Replay attack prevention: Any handler that processes time-sensitive payloads needs to confirm the request timestamp falls within an acceptable window before trusting the body.
How it works
The submodule provides two layers of functionality. The lower layer handles raw data operations: producing digests from arbitrary input, generating signatures from a secret and a message, and converting between common binary encodings. These primitives are the building blocks for anything that needs to prove or check data integrity.
The upper layer builds on those primitives to implement the specific signature schemes used by popular webhook providers. Each verifier takes the raw request body, the signature header, and a secret, then checks whether the signature matches and whether the timestamp is recent enough. Results come back as a structured success or failure value with a specific error code, so a handler can respond appropriately without parsing error strings.
Secrets used for verification should be stored in private tables within the module, keeping them out of any publicly readable rows or reducer outputs. Verification should always happen against the raw, unparsed body, since even minor formatting changes would cause a legitimate signature to fail.
