registrystack / registrystack/registry-stack
Expose the BReg webhook signature verifier in @registrystack/client
- Dominant language
- Rust
- Stars
- 2
- Forks
- 0
- Avg merge
- 2h 55m
- Merged PRs (30d)
- 130
Description
## What Happened
The BReg webhook signature contract (`breg-webhook-signature-v1`: HMAC-SHA256 over fourteen length-prefixed fields, see `reference/breg-api` "Events and webhooks") has exactly one implementation of the verifier, `verify_v1` in `registry-platform-crypto`. A Node receiver has to re-implement it. The OpenFn pilot did (`registrystack/openfn-language-registry-stack`, `services/event-bridge/src/server.js`): header ordering, length prefixing and constant-time comparison, all hand-written.
## Expected Behavior
`@registrystack/client` exposes the verifier as a narrow protocol helper, for example `breg.verifyWebhookDelivery({ method, path, headers, body, key })` returning a typed verified envelope or a closed refusal code. It is a napi binding over the existing Rust function, so the only contract is the one already documented. Python parity follows the same pattern if the Python client carries webhooks.
## Scope
- Binding plus TypeScript types in `crates/registry-stack-client-node/breg` and `crates/registry-breg-client-node`.
- Tests: the existing signing fixtures from `crates/registry-breg/src/webhook.rs` replayed through the Node verifier, plus tampered header, tampered body, wrong key, skewed delivery time (skew policy stays with the caller and is passed in).
- One worked receiver example in `reference/client-api`.
## Environment
0.30.0.
Triage: next release. The pilot's bridge should adopt it once shipped.
Contributor guide
Research direction
Start with verify_v1 in registry-platform-crypto and the existing signing fixtures in crates/registry-breg/src/webhook.rs. Then inspect crates/registry-stack-client-node/breg, crates/registry-breg-client-node, and the OpenFn receiver for the binding and type boundaries. Done means the Node verifier replays the fixtures, rejects the listed tampering cases, and has a worked example in reference/client-api.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- node.js, rust, typescript
- Domain
- api, documentation, security
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 65/100