Initial Commit

openspec/archive/2026-04-19-enterprise-webhook-client/proposal.md

@@ -0,0 +1,56 @@
+# OpenSpec Change: enterprise-webhook-client
+
+- **Change ID**: enterprise-webhook-client
+- **Package**: `@suaveplan/webhook-client`
+- **Category**: universal
+- **Target path**: `universal/messaging/webhook-client`
+- **Status**: PROPOSED
+- **Date**: 2026-04-19
+- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/webhook-client.md`
+
+## Summary
+
+Greenfield rebuild of `@suaveplan/webhook-client` — outgoing webhook receiver with signature verification, configurable parser and schema registry, HMAC / JWS signature schemes, listener API, and a hook surface for pre/post delivery observability. Signs outgoing requests with `@suaveplan/crypto`.
+
+## Current-state audit (genesis)
+
+Package does not exist yet — fresh build.
+
+## Dependencies
+
+- Workspace: `@suaveplan/error`, `@suaveplan/events`, `@suaveplan/types`, `@suaveplan/crypto`
+- External (via catalog): `zod`, `tslib`, `@opentelemetry/api`
+- Dev (via catalog): `vitest`, `@vitest/coverage-istanbul`, `fast-check`, `mitata`
+
+## Preserved public surface
+
+### Receiver / parser / verifier
+
+- `WebhookReceiver`, `ReceiverErrorCode`, `WebhookListener`
+- `WebhookParser`, `ParserErrorCode`
+- `WebhookVerifier`, `VerifierErrorCode`
+
+### Hooks
+
+- `onWebhookDelivering`, `webhookHooks`, `WebhookDeliveringHookData`, `WebhookHookMap`
+
+### Error codes
+
+- `WebhookErrorCode`, `WEBHOOK_ERROR_METADATA`, `registerWebhookErrorCodes`
+
+### Types
+
+`ParsedWebhookEvent`, `SignatureScheme`, `VerificationResult`, `WebhookConfig`, `WebhookPayload`, `WebhookSchema`.
+
+## New genesis additions
+
+- Codes: `WEBHOOK.INVALID_SIGNATURE`, `WEBHOOK.REPLAY_DETECTED`, `WEBHOOK.SCHEMA_MISMATCH`, `WEBHOOK.LISTENER_ERROR`.
+- Zod schemas for every type.
+- Timestamp-based replay protection (`WebhookConfig.maxSkewSeconds`).
+- OTel histograms `webhook.receive.duration_ms`, `webhook.verify.duration_ms`; counters for outcome.
+- Property tests: HMAC sign/verify round-trip; replay rejection above skew.
+
+## Impact
+
+- Adds one new package: `universal/messaging/webhook-client`
+- Adds one new spec capability: `webhook-client`

openspec/archive/2026-04-19-enterprise-webhook-client/specs/webhook-client/spec.md

@@ -0,0 +1,33 @@
+# Capability Spec: webhook-client
+
+**Package**: `@suaveplan/webhook-client`
+**Version**: 0.0.0 (genesis)
+**Status**: ADDED
+
+---
+
+## ADDED Requirements
+
+### WH-01 — Signature schemes
+
+`SignatureScheme` MUST include `'hmac-sha256'` and `'jws'`. `WebhookVerifier.verify(request, config)` MUST compute the signature per scheme and compare in constant time. Mismatches MUST throw `WEBHOOK.INVALID_SIGNATURE`.
+
+### WH-02 — Replay protection
+
+`WebhookConfig.maxSkewSeconds` (default 300) MUST bound the accepted timestamp delta. Requests outside the skew MUST throw `WEBHOOK.REPLAY_DETECTED`. The verifier MUST include the timestamp in the signing-string.
+
+### WH-03 — Parse contract
+
+`WebhookParser.parse(request)` MUST accept `application/json`, `application/x-www-form-urlencoded`, and `text/plain`. Payloads MUST be Zod-validated against the configured `WebhookSchema`. Validation failures MUST throw `WEBHOOK.SCHEMA_MISMATCH`.
+
+### WH-04 — Receiver
+
+`WebhookReceiver.handle(request)` MUST run verify → parse → dispatch-listeners. Listener exceptions MUST be captured per-listener, emit `WEBHOOK.LISTENER_ERROR` with context, and continue with the remaining listeners.
+
+### WH-05 — Hooks
+
+`webhookHooks.delivering` MUST fire with `WebhookDeliveringHookData { event, listener, startedAt }` before each listener invocation. Handlers MUST be able to veto delivery by throwing.
+
+### WH-06 — Observability
+
+Every `handle` call MUST record `webhook.receive.duration_ms`; every verify MUST record `webhook.verify.duration_ms`; outcome counters MUST label `scheme` and `result`.

openspec/archive/2026-04-19-enterprise-webhook-client/tasks.md

@@ -0,0 +1,36 @@
+# Tasks: enterprise-webhook-client
+
+## 1. Scaffold
+
+- [x] 1.1 `universal/messaging/webhook-client/`; 100/100/100/100; guard tests; CLAUDE/README/FOLDERS.
+
+## 2. Errors + schemas
+
+- [x] 2.1 `src/errors/error-codes.ts` — codes + register; `WebhookErrorCode`.
+- [x] 2.2 Zod schemas per type.
+
+## 3. Verifier
+
+- [x] 3.1 `src/verifier/verifier.ts` — `WebhookVerifier` (HMAC-SHA256 + JWS); timing-safe compare via `@suaveplan/crypto`.
+
+## 4. Parser
+
+- [x] 4.1 `src/parser/parser.ts` — `WebhookParser` (JSON + form-encoded); schema validation with Zod-provided `WebhookSchema`.
+
+## 5. Receiver
+
+- [x] 5.1 `src/receiver/receiver.ts` — `WebhookReceiver` (request ingestion + listener dispatch + replay protection).
+
+## 6. Hooks
+
+- [x] 6.1 `src/hooks.ts` — `onWebhookDelivering`, `webhookHooks`.
+
+## 7. Docs / barrel / subpath exports / README
+
+## 8. Benchmarks
+
+- [x] 8.1 `verify.bench.ts`, `receive.bench.ts`.
+
+## 9. Ship gate
+
+- [x] 9.1 Verification sequence; fold + archive.