registrystack / registrystack/registry-stack

Expose the BReg webhook signature verifier in @registrystack/client

Open
#1,018 0 comments 0 reactions 0 assignees View on GitHub
agent-ready area:breg area:platform criticality:p2 enhancement
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.