@openwop/openwop 1.7.0 → 1.9.0

package/dist/index.d.ts

@@ -21,8 +21,11 @@ export { ACTIVE_RUN_STATUSES, TERMINAL_RUN_STATUSES, isTerminalRunStatus, HTTP_E
 export type { ActiveRunStatus, TerminalRunStatus, HttpErrorCode, RunErrorCode, RunError, } from './run-helpers.js';
 export { OPENWOP_COST_ATTRIBUTE_NAMES, sanitizeCostAttributes, } from './cost-attribution.js';
 export type { OpenwopCostAttributeName } from './cost-attribution.js';
+/** @deprecated Import from `@openwop/openwop/webhooks` — server-only; removed from the barrel in the next major. */
 export { DEFAULT_WEBHOOK_FRESHNESS_WINDOW_SECONDS, verifyWebhookSignature, signWebhookDelivery, } from './webhook-helpers.js';
-export type { VerifyWebhookSignatureOptions, VerifyWebhookOutcome, } from './webhook-helpers.js';
+export type { VerifyWebhookSignatureOptions, VerifyWebhookOutcome, SignedWebhookDelivery, } from './webhook-helpers.js';
+export { WEBHOOK_HEADER_FAMILIES, parseSignatureValue, readWebhookHeaders } from './webhook-header-families.js';
+export type { WebhookHeaderRead } from './webhook-header-families.js';
 export { RegistryClient } from './registry-helpers.js';
 export type { RegistryClientOptions, RegistryDiscovery, RegistryIndex, RegistryIndexEntry, RegistryPackMetadata, RegistryVersionManifest, } from './registry-helpers.js';
 export type { A2UISurfacePayload, A2uiSurfaceDeltaFrame, A2uiSurfacePatchOp, AIEnvelope, AIEnvelopeErrorPayload, ClarificationRequestPayload, EnvelopeContract, EnvelopeContractRefusal, EnvelopeContractsCapability, EnvelopeMeta, EnvelopeOutcome, EnvelopeStrictness, PartialInfo, SchemaRequestPayload, SchemaResponsePayload, ValidationDetail, LocalizedContentStatus, LocalizedContentPage, LocalizedContentSection, LocalizedContentPageResponse, LocalizedContentLanguageSettings, PutContentSectionRequest, TriggerSubscriptionRegistration, TriggerSubscription, CreateTriggerSubscriptionResponse, } from './types.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -28,7 +28,22 @@ export { OPENWOP_COST_ATTRIBUTE_NAMES, sanitizeCostAttributes, } from './cost-at
 // HMAC-SHA256 + timestamp freshness window verification per
 // spec/v1/webhooks.md §"Signature recipe". Receivers MUST verify both
 // the HMAC AND the timestamp to defeat replay attacks.
+//
+// DEPRECATED ON THE BARREL (openwop-sdks#30). These re-exports are why a
+// browser consumer importing anything at all from `@openwop/openwop` dragged
+// in `node:crypto` and failed the build. Import them from
+// `@openwop/openwop/webhooks` instead; the barrel re-export is retained for
+// compatibility and will be removed in the next major.
+//
+// Until then the `browser` field in package.json substitutes a stub that
+// throws with an explanatory message, so a browser build succeeds and only a
+// browser CALL fails — which is the correct outcome either way, since the
+// subscription secret must never reach a browser.
+/** @deprecated Import from `@openwop/openwop/webhooks` — server-only; removed from the barrel in the next major. */
 export { DEFAULT_WEBHOOK_FRESHNESS_WINDOW_SECONDS, verifyWebhookSignature, signWebhookDelivery, } from './webhook-helpers.js';
+// RFC 0165 §C.3 — browser-safe (no Node builtin): which header family a
+// delivery carries, and the `sha256=` / legacy `v1=` value parser.
+export { WEBHOOK_HEADER_FAMILIES, parseSignatureValue, readWebhookHeaders } from './webhook-header-families.js';
 // Public-registry read helpers (SDK-5 close-out 2026-05-15). Read-only
 // typed client for the public node-pack registry at packs.openwop.dev
 // per spec/v1/registry-operations.md.

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AA8GtC,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAGxC,2EAA2E;AAC3E,6DAA6D;AAC7D,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,iBAAiB,EACjB,mBAAmB,EACnB,cAAc,EACd,cAAc,EACd,eAAe,EACf,aAAa,EACb,kBAAkB,EAClB,iBAAiB,EACjB,wBAAwB,EACxB,iBAAiB,EACjB,qBAAqB,EACrB,cAAc,EACd,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,cAAc,EACd,mBAAmB,EACnB,yBAAyB,GAC1B,MAAM,oBAAoB,CAAC;AAM5B,yEAAyE;AACzE,yEAAyE;AACzE,oBAAoB;AACpB,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,mBAAmB,EACnB,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,cAAc,GACf,MAAM,kBAAkB,CAAC;AAS1B,iDAAiD;AACjD,sEAAsE;AACtE,mEAAmE;AACnE,uDAAuD;AACvD,OAAO,EACL,4BAA4B,EAC5B,sBAAsB,GACvB,MAAM,uBAAuB,CAAC;AAG/B,sEAAsE;AACtE,4DAA4D;AAC5D,sEAAsE;AACtE,uDAAuD;AACvD,OAAO,EACL,wCAAwC,EACxC,sBAAsB,EACtB,mBAAmB,GACpB,MAAM,sBAAsB,CAAC;AAM9B,uEAAuE;AACvE,sEAAsE;AACtE,sCAAsC;AACtC,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AA0CvD,oEAAoE;AACpE,wEAAwE;AACxE,uEAAuE;AACvE,uEAAuE;AACvE,oEAAoE;AACpE,uDAAuD;AACvD,OAAO,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAGlE,mEAAmE;AACnE,wEAAwE;AACxE,uEAAuE;AACvE,qEAAqE;AACrE,qEAAqE;AACrE,sEAAsE;AACtE,8DAA8D;AAC9D,sEAAsE;AACtE,oDAAoD;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AA8GtC,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAGxC,2EAA2E;AAC3E,6DAA6D;AAC7D,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,iBAAiB,EACjB,mBAAmB,EACnB,cAAc,EACd,cAAc,EACd,eAAe,EACf,aAAa,EACb,kBAAkB,EAClB,iBAAiB,EACjB,wBAAwB,EACxB,iBAAiB,EACjB,qBAAqB,EACrB,cAAc,EACd,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,cAAc,EACd,mBAAmB,EACnB,yBAAyB,GAC1B,MAAM,oBAAoB,CAAC;AAM5B,yEAAyE;AACzE,yEAAyE;AACzE,oBAAoB;AACpB,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,mBAAmB,EACnB,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,cAAc,GACf,MAAM,kBAAkB,CAAC;AAS1B,iDAAiD;AACjD,sEAAsE;AACtE,mEAAmE;AACnE,uDAAuD;AACvD,OAAO,EACL,4BAA4B,EAC5B,sBAAsB,GACvB,MAAM,uBAAuB,CAAC;AAG/B,sEAAsE;AACtE,4DAA4D;AAC5D,sEAAsE;AACtE,uDAAuD;AACvD,EAAE;AACF,yEAAyE;AACzE,6EAA6E;AAC7E,0DAA0D;AAC1D,4EAA4E;AAC5E,uDAAuD;AACvD,EAAE;AACF,yEAAyE;AACzE,6EAA6E;AAC7E,0EAA0E;AAC1E,kDAAkD;AAClD,oHAAoH;AACpH,OAAO,EACL,wCAAwC,EACxC,sBAAsB,EACtB,mBAAmB,GACpB,MAAM,sBAAsB,CAAC;AAM9B,wEAAwE;AACxE,mEAAmE;AACnE,OAAO,EAAE,uBAAuB,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAGhH,uEAAuE;AACvE,sEAAsE;AACtE,sCAAsC;AACtC,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AA0CvD,oEAAoE;AACpE,wEAAwE;AACxE,uEAAuE;AACvE,uEAAuE;AACvE,oEAAoE;AACpE,uDAAuD;AACvD,OAAO,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAGlE,mEAAmE;AACnE,wEAAwE;AACxE,uEAAuE;AACvE,qEAAqE;AACrE,qEAAqE;AACrE,sEAAsE;AACtE,8DAA8D;AAC9D,sEAAsE;AACtE,oDAAoD;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/webhook-header-families.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Webhook header families and signature-value parsing (RFC 0165 §C.3).
+ * Pure — no Node builtin — so both the server module (`webhook-helpers.ts`)
+ * and the browser stub re-export it. Verification itself stays server-only.
+ */
+/** `sha256=<hex>` or `v1=<hex>` → `<hex>`; anything else → null. */
+export declare function parseSignatureValue(value: string): string | null;
+/**
+ * Header-name families a delivery may carry, in the order a receiver SHOULD
+ * prefer them (RFC 0165 §C.1): the v2-bound `OpenWOP-*` family, the v1
+ * canonical `X-openwop-*` family, then the legacy names this SDK used to
+ * document. Lookups are case-insensitive.
+ */
+export declare const WEBHOOK_HEADER_FAMILIES: ReadonlyArray<{
+    readonly signature: string;
+    readonly timestamp: string;
+    readonly algorithm?: string;
+}>;
+export interface WebhookHeaderRead {
+    readonly signatureHeader: string;
+    readonly timestampHeader: string;
+    /** Which family was read: `openwop`, `x-openwop`, or `legacy`. */
+    readonly family: 'openwop' | 'x-openwop' | 'legacy';
+}
+/**
+ * Pick the signature + timestamp values out of a delivery's headers, first
+ * present family wins. Returns null when no family is complete. Pass a plain
+ * object (any casing) or a `Headers`-like with a `get` method.
+ */
+export declare function readWebhookHeaders(headers: Record<string, string | string[] | undefined> | {
+    get(name: string): string | null;
+}): WebhookHeaderRead | null;
+//# sourceMappingURL=webhook-header-families.d.ts.map

package/dist/webhook-header-families.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-header-families.d.ts","sourceRoot":"","sources":["../src/webhook-header-families.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,oEAAoE;AACpE,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAQhE;AAED;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,EAAE,aAAa,CAAC;IAAE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CAI1I,CAAC;AAEF,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,kEAAkE;IAClE,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,WAAW,GAAG,QAAQ,CAAC;CACrD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,GAAG;IAAE,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;CAAE,GAC5F,iBAAiB,GAAG,IAAI,CAmB1B"}

package/dist/webhook-header-families.js

@@ -0,0 +1,55 @@
+/**
+ * Webhook header families and signature-value parsing (RFC 0165 §C.3).
+ * Pure — no Node builtin — so both the server module (`webhook-helpers.ts`)
+ * and the browser stub re-export it. Verification itself stays server-only.
+ */
+/** Accepted signature-value prefixes, spec form first. */
+const SIGNATURE_VALUE_PREFIXES = ['sha256=', 'v1='];
+/** `sha256=<hex>` or `v1=<hex>` → `<hex>`; anything else → null. */
+export function parseSignatureValue(value) {
+    for (const p of SIGNATURE_VALUE_PREFIXES) {
+        if (value.startsWith(p)) {
+            const hex = value.slice(p.length);
+            return /^[0-9a-f]+$/i.test(hex) ? hex : null;
+        }
+    }
+    return null;
+}
+/**
+ * Header-name families a delivery may carry, in the order a receiver SHOULD
+ * prefer them (RFC 0165 §C.1): the v2-bound `OpenWOP-*` family, the v1
+ * canonical `X-openwop-*` family, then the legacy names this SDK used to
+ * document. Lookups are case-insensitive.
+ */
+export const WEBHOOK_HEADER_FAMILIES = [
+    { signature: 'OpenWOP-Signature', timestamp: 'OpenWOP-Timestamp', algorithm: 'OpenWOP-Signature-Algorithm' },
+    { signature: 'X-openwop-Signature', timestamp: 'X-openwop-Timestamp', algorithm: 'X-openwop-Signature-Algorithm' },
+    { signature: 'openwop-Webhook-Signature', timestamp: 'openwop-Webhook-Timestamp' },
+];
+/**
+ * Pick the signature + timestamp values out of a delivery's headers, first
+ * present family wins. Returns null when no family is complete. Pass a plain
+ * object (any casing) or a `Headers`-like with a `get` method.
+ */
+export function readWebhookHeaders(headers) {
+    const get = (name) => {
+        if (typeof headers.get === 'function') {
+            const v = headers.get(name);
+            return v === null ? undefined : v;
+        }
+        const rec = headers;
+        const key = Object.keys(rec).find((k) => k.toLowerCase() === name.toLowerCase());
+        const v = key === undefined ? undefined : rec[key];
+        return Array.isArray(v) ? v[0] : v;
+    };
+    const families = ['openwop', 'x-openwop', 'legacy'];
+    for (let i = 0; i < WEBHOOK_HEADER_FAMILIES.length; i++) {
+        const f = WEBHOOK_HEADER_FAMILIES[i];
+        const sig = get(f.signature);
+        const ts = get(f.timestamp);
+        if (sig !== undefined && ts !== undefined)
+            return { signatureHeader: sig, timestampHeader: ts, family: families[i] };
+    }
+    return null;
+}
+//# sourceMappingURL=webhook-header-families.js.map

package/dist/webhook-header-families.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-header-families.js","sourceRoot":"","sources":["../src/webhook-header-families.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,0DAA0D;AAC1D,MAAM,wBAAwB,GAAG,CAAC,SAAS,EAAE,KAAK,CAAU,CAAC;AAE7D,oEAAoE;AACpE,MAAM,UAAU,mBAAmB,CAAC,KAAa;IAC/C,KAAK,MAAM,CAAC,IAAI,wBAAwB,EAAE,CAAC;QACzC,IAAI,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC;YACxB,MAAM,GAAG,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;YAClC,OAAO,cAAc,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;QAC/C,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAA2G;IAC7I,EAAE,SAAS,EAAE,mBAAmB,EAAE,SAAS,EAAE,mBAAmB,EAAE,SAAS,EAAE,6BAA6B,EAAE;IAC5G,EAAE,SAAS,EAAE,qBAAqB,EAAE,SAAS,EAAE,qBAAqB,EAAE,SAAS,EAAE,+BAA+B,EAAE;IAClH,EAAE,SAAS,EAAE,2BAA2B,EAAE,SAAS,EAAE,2BAA2B,EAAE;CACnF,CAAC;AASF;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAChC,OAA6F;IAE7F,MAAM,GAAG,GAAG,CAAC,IAAY,EAAsB,EAAE;QAC/C,IAAI,OAAQ,OAA6B,CAAC,GAAG,KAAK,UAAU,EAAE,CAAC;YAC7D,MAAM,CAAC,GAAI,OAAgD,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACtE,OAAO,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;QACpC,CAAC;QACD,MAAM,GAAG,GAAG,OAAwD,CAAC;QACrE,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,KAAK,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;QACjF,MAAM,CAAC,GAAG,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACnD,OAAO,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACrC,CAAC,CAAC;IACF,MAAM,QAAQ,GAAG,CAAC,SAAS,EAAE,WAAW,EAAE,QAAQ,CAAU,CAAC;IAC7D,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,uBAAuB,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACxD,MAAM,CAAC,GAAG,uBAAuB,CAAC,CAAC,CAAE,CAAC;QACtC,MAAM,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QAC7B,MAAM,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QAC5B,IAAI,GAAG,KAAK,SAAS,IAAI,EAAE,KAAK,SAAS;YAAE,OAAO,EAAE,eAAe,EAAE,GAAG,EAAE,eAAe,EAAE,EAAE,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAE,EAAE,CAAC;IACxH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/webhook-helpers.browser.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Browser substitute for `webhook-helpers.ts` (openwop-sdks#30).
+ *
+ * ## Why this file exists
+ *
+ * `webhook-helpers.ts` imports `node:crypto` for `createHmac` and
+ * `timingSafeEqual`. The package barrel re-exports it, and the `exports` map
+ * offers only `"."` — so a browser consumer importing ANYTHING from
+ * `@openwop/openwop` pulled the barrel, pulled the webhook helpers, and pulled
+ * `node:crypto`. Vite/Rollup then failed the BUILD with
+ *
+ *     "createHmac" is not exported by "__vite-browser-external"
+ *
+ * which names a bundler-internal shim rather than the real cause, so the error
+ * points nowhere useful. Reported 2026-05-26 and still reproducible against the
+ * published 1.7.0 fifteen months later.
+ *
+ * The `browser` field in package.json maps the Node module to this one, so the
+ * barrel is importable in a browser again. Webhook signature verification is a
+ * SERVER concern — a browser has no business holding the subscription secret —
+ * so the honest browser behaviour is to keep the import working and refuse the
+ * call, not to ship a second crypto implementation.
+ *
+ * ## Why it throws rather than returning a failure
+ *
+ * `verifyWebhookSignature` returning `{ ok: false }` in a browser would be a
+ * silent security downgrade: a caller that treats "not ok" as "reject the
+ * delivery" behaves identically whether the signature was forged or the
+ * platform simply could not check it. Those are different facts and only one of
+ * them is about the payload. Throwing keeps them distinguishable.
+ */
+/** @see spec/v1/webhooks.md §"Replay attack protection" */
+export declare const DEFAULT_WEBHOOK_FRESHNESS_WINDOW_SECONDS = 300;
+export declare function verifyWebhookSignature(): never;
+export declare function signWebhookDelivery(): never;
+export { WEBHOOK_HEADER_FAMILIES, parseSignatureValue, readWebhookHeaders } from './webhook-header-families.js';
+export type { VerifyWebhookSignatureOptions, VerifyWebhookOutcome, SignedWebhookDelivery, WebhookHeaderRead } from './webhook-helpers.js';
+//# sourceMappingURL=webhook-helpers.browser.d.ts.map

package/dist/webhook-helpers.browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-helpers.browser.d.ts","sourceRoot":"","sources":["../src/webhook-helpers.browser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAOH,2DAA2D;AAC3D,eAAO,MAAM,wCAAwC,MAAM,CAAC;AAE5D,wBAAgB,sBAAsB,IAAI,KAAK,CAE9C;AAED,wBAAgB,mBAAmB,IAAI,KAAK,CAE3C;AAKD,OAAO,EAAE,uBAAuB,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAEhH,YAAY,EAAE,6BAA6B,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/webhook-helpers.browser.js

@@ -0,0 +1,47 @@
+/**
+ * Browser substitute for `webhook-helpers.ts` (openwop-sdks#30).
+ *
+ * ## Why this file exists
+ *
+ * `webhook-helpers.ts` imports `node:crypto` for `createHmac` and
+ * `timingSafeEqual`. The package barrel re-exports it, and the `exports` map
+ * offers only `"."` — so a browser consumer importing ANYTHING from
+ * `@openwop/openwop` pulled the barrel, pulled the webhook helpers, and pulled
+ * `node:crypto`. Vite/Rollup then failed the BUILD with
+ *
+ *     "createHmac" is not exported by "__vite-browser-external"
+ *
+ * which names a bundler-internal shim rather than the real cause, so the error
+ * points nowhere useful. Reported 2026-05-26 and still reproducible against the
+ * published 1.7.0 fifteen months later.
+ *
+ * The `browser` field in package.json maps the Node module to this one, so the
+ * barrel is importable in a browser again. Webhook signature verification is a
+ * SERVER concern — a browser has no business holding the subscription secret —
+ * so the honest browser behaviour is to keep the import working and refuse the
+ * call, not to ship a second crypto implementation.
+ *
+ * ## Why it throws rather than returning a failure
+ *
+ * `verifyWebhookSignature` returning `{ ok: false }` in a browser would be a
+ * silent security downgrade: a caller that treats "not ok" as "reject the
+ * delivery" behaves identically whether the signature was forged or the
+ * platform simply could not check it. Those are different facts and only one of
+ * them is about the payload. Throwing keeps them distinguishable.
+ */
+const REASON = 'openwop: webhook signature helpers require Node\'s crypto (HMAC-SHA256 + timingSafeEqual) and are not available in a browser build. '
+    + 'Webhook verification is a server-side concern — the subscription secret must never reach a browser. '
+    + 'Import them on the server from "@openwop/openwop/webhooks".';
+/** @see spec/v1/webhooks.md §"Replay attack protection" */
+export const DEFAULT_WEBHOOK_FRESHNESS_WINDOW_SECONDS = 300;
+export function verifyWebhookSignature() {
+    throw new Error(REASON);
+}
+export function signWebhookDelivery() {
+    throw new Error(REASON);
+}
+// RFC 0165 §C.3 — the header-family readers need no Node builtin, so the
+// browser build carries the real implementations (a browser MAY inspect which
+// family a delivery carries; it still MUST NOT verify — no secret in a browser).
+export { WEBHOOK_HEADER_FAMILIES, parseSignatureValue, readWebhookHeaders } from './webhook-header-families.js';
+//# sourceMappingURL=webhook-helpers.browser.js.map

package/dist/webhook-helpers.browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-helpers.browser.js","sourceRoot":"","sources":["../src/webhook-helpers.browser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,MAAM,MAAM,GACV,sIAAsI;MACpI,sGAAsG;MACtG,6DAA6D,CAAC;AAElE,2DAA2D;AAC3D,MAAM,CAAC,MAAM,wCAAwC,GAAG,GAAG,CAAC;AAE5D,MAAM,UAAU,sBAAsB;IACpC,MAAM,IAAI,KAAK,CAAC,MAAM,CAAC,CAAC;AAC1B,CAAC;AAED,MAAM,UAAU,mBAAmB;IACjC,MAAM,IAAI,KAAK,CAAC,MAAM,CAAC,CAAC;AAC1B,CAAC;AAED,yEAAyE;AACzE,8EAA8E;AAC9E,iFAAiF;AACjF,OAAO,EAAE,uBAAuB,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC"}

package/dist/webhook-helpers.d.ts

@@ -4,15 +4,23 @@
  * timestamp freshness before accepting a delivery — verifying HMAC
  * alone leaves the receiver open to replay attacks.
  *
- * The canonical signing recipe:
+ * The canonical signing recipe (`webhooks.md` §"Headers"):
  *
  *     hmac = HMAC-SHA256(secret, `${timestamp}.${rawBody}`)
- *     header `openwop-Webhook-Signature: v1=<hmac-hex>`
- *     header `openwop-Webhook-Timestamp: <unix-seconds>`
+ *     header `X-openwop-Signature: sha256=<hmac-hex>`        (v1 canonical)
+ *     header `OpenWOP-Signature: sha256=<hmac-hex>`          (RFC 0165 §C.1, dual-emitted)
+ *     header `X-openwop-Timestamp` / `OpenWOP-Timestamp: <unix-seconds>`
+ *
+ * History (RFC 0165 §C.3): until 1.9.0 this helper read a header named
+ * `openwop-Webhook-Signature` carrying `v1=<hex>` — a name and value shape
+ * that appear in no spec file. A spec-conformant `sha256=` delivery failed
+ * verification outright. The helper now accepts BOTH value forms, and
+ * `readWebhookHeaders` picks the first present header family in spec order
+ * (`OpenWOP-*`, then `X-openwop-*`, then the legacy `openwop-Webhook-*`).
  *
  * Verification:
  *
- *   1. Parse the `v1=<hex>` value from the signature header.
+ *   1. Parse the `sha256=<hex>` (or legacy `v1=<hex>`) value from the signature header.
  *   2. Recompute `expected = HMAC-SHA256(secret, `${timestamp}.${rawBody}`)`.
  *   3. Compare using **constant-time** equality (timing-safe).
  *   4. Reject when `|now - timestamp|` exceeds the freshness window
@@ -55,19 +63,27 @@ export type VerifyWebhookOutcome = {
  * signs the exact bytes it delivered.
  *
  * @param secret The pre-shared secret returned from `webhooks.register`.
- * @param signatureHeader The value of the `openwop-Webhook-Signature` header (e.g., `"v1=abc123…"`).
- * @param timestampHeader The value of the `openwop-Webhook-Timestamp` header (unix seconds as string).
+ * @param signatureHeader The value of the signature header — `OpenWOP-Signature` / `X-openwop-Signature` (`"sha256=abc123…"`) or the legacy `openwop-Webhook-Signature` (`"v1=abc123…"`); see `readWebhookHeaders`.
+ * @param timestampHeader The value of the matching timestamp header (unix seconds as string).
  * @param rawBody The exact request body bytes the host POSTed.
  */
 export declare function verifyWebhookSignature(secret: string, signatureHeader: string, timestampHeader: string, rawBody: string | Buffer, options?: VerifyWebhookSignatureOptions): VerifyWebhookOutcome;
+export interface SignedWebhookDelivery {
+    /** Spec form: `sha256=<hex>` (webhooks.md §"Headers"). */
+    readonly signatureHeader: string;
+    /** Legacy form this SDK used to emit: `v1=<hex>` (RFC 0165 §C.3). */
+    readonly legacySignatureHeader: string;
+    readonly timestampHeader: string;
+    /** Every header a host should send during the RFC 0165 overlap, by exact name. */
+    readonly headers: Readonly<Record<string, string>>;
+}
 /**
  * Compute the canonical webhook signature for a payload — useful when
  * implementing a host (forward direction) OR when generating test
  * fixtures. Receivers verify via `verifyWebhookSignature`; this is the
  * inverse.
  */
-export declare function signWebhookDelivery(secret: string, timestamp: number, rawBody: string | Buffer): {
-    signatureHeader: string;
-    timestampHeader: string;
-};
+export declare function signWebhookDelivery(secret: string, timestamp: number, rawBody: string | Buffer): SignedWebhookDelivery;
+export { WEBHOOK_HEADER_FAMILIES, parseSignatureValue, readWebhookHeaders } from './webhook-header-families.js';
+export type { WebhookHeaderRead } from './webhook-header-families.js';
 //# sourceMappingURL=webhook-helpers.d.ts.map

package/dist/webhook-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"webhook-helpers.d.ts","sourceRoot":"","sources":["../src/webhook-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAIH,sFAAsF;AACtF,eAAO,MAAM,wCAAwC,MAAM,CAAC;AAE5D,MAAM,WAAW,6BAA6B;IAC5C;;;;OAIG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,MAAM,oBAAoB,GAC5B;IAAE,KAAK,EAAE,IAAI,CAAA;CAAE,GACf;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,oBAAoB,GAAG,mBAAmB,GAAG,6BAA6B,GAAG,4BAA4B,GAAG,4BAA4B,CAAA;CAAE,CAAC;AAEvK;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,MAAM,EACd,eAAe,EAAE,MAAM,EACvB,eAAe,EAAE,MAAM,EACvB,OAAO,EAAE,MAAM,GAAG,MAAM,EACxB,OAAO,GAAE,6BAAkC,GAC1C,oBAAoB,CAyCtB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,GAAG,MAAM,GACvB;IAAE,eAAe,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,MAAM,CAAA;CAAE,CAOtD"}
+{"version":3,"file":"webhook-helpers.d.ts","sourceRoot":"","sources":["../src/webhook-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAKH,sFAAsF;AACtF,eAAO,MAAM,wCAAwC,MAAM,CAAC;AAE5D,MAAM,WAAW,6BAA6B;IAC5C;;;;OAIG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,MAAM,oBAAoB,GAC5B;IAAE,KAAK,EAAE,IAAI,CAAA;CAAE,GACf;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,oBAAoB,GAAG,mBAAmB,GAAG,6BAA6B,GAAG,4BAA4B,GAAG,4BAA4B,CAAA;CAAE,CAAC;AAEvK;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,MAAM,EACd,eAAe,EAAE,MAAM,EACvB,eAAe,EAAE,MAAM,EACvB,OAAO,EAAE,MAAM,GAAG,MAAM,EACxB,OAAO,GAAE,6BAAkC,GAC1C,oBAAoB,CA0CtB;AAED,MAAM,WAAW,qBAAqB;IACpC,0DAA0D;IAC1D,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,qEAAqE;IACrE,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,kFAAkF;IAClF,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACpD;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,GAAG,MAAM,GACvB,qBAAqB,CAkBvB;AAED,OAAO,EAAE,uBAAuB,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAChH,YAAY,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC"}

package/dist/webhook-helpers.js

@@ -4,15 +4,23 @@
  * timestamp freshness before accepting a delivery — verifying HMAC
  * alone leaves the receiver open to replay attacks.
  *
- * The canonical signing recipe:
+ * The canonical signing recipe (`webhooks.md` §"Headers"):
  *
  *     hmac = HMAC-SHA256(secret, `${timestamp}.${rawBody}`)
- *     header `openwop-Webhook-Signature: v1=<hmac-hex>`
- *     header `openwop-Webhook-Timestamp: <unix-seconds>`
+ *     header `X-openwop-Signature: sha256=<hmac-hex>`        (v1 canonical)
+ *     header `OpenWOP-Signature: sha256=<hmac-hex>`          (RFC 0165 §C.1, dual-emitted)
+ *     header `X-openwop-Timestamp` / `OpenWOP-Timestamp: <unix-seconds>`
+ *
+ * History (RFC 0165 §C.3): until 1.9.0 this helper read a header named
+ * `openwop-Webhook-Signature` carrying `v1=<hex>` — a name and value shape
+ * that appear in no spec file. A spec-conformant `sha256=` delivery failed
+ * verification outright. The helper now accepts BOTH value forms, and
+ * `readWebhookHeaders` picks the first present header family in spec order
+ * (`OpenWOP-*`, then `X-openwop-*`, then the legacy `openwop-Webhook-*`).
  *
  * Verification:
  *
- *   1. Parse the `v1=<hex>` value from the signature header.
+ *   1. Parse the `sha256=<hex>` (or legacy `v1=<hex>`) value from the signature header.
  *   2. Recompute `expected = HMAC-SHA256(secret, `${timestamp}.${rawBody}`)`.
  *   3. Compare using **constant-time** equality (timing-safe).
  *   4. Reject when `|now - timestamp|` exceeds the freshness window
@@ -25,6 +33,7 @@
  * @module @openwop/openwop/webhook-helpers
  */
 import { createHmac, timingSafeEqual } from 'node:crypto';
+import { parseSignatureValue } from './webhook-header-families.js';
 /** Default freshness window per `spec/v1/webhooks.md` §"Replay attack resistance". */
 export const DEFAULT_WEBHOOK_FRESHNESS_WINDOW_SECONDS = 300;
 /**
@@ -37,16 +46,17 @@ export const DEFAULT_WEBHOOK_FRESHNESS_WINDOW_SECONDS = 300;
  * signs the exact bytes it delivered.
  *
  * @param secret The pre-shared secret returned from `webhooks.register`.
- * @param signatureHeader The value of the `openwop-Webhook-Signature` header (e.g., `"v1=abc123…"`).
- * @param timestampHeader The value of the `openwop-Webhook-Timestamp` header (unix seconds as string).
+ * @param signatureHeader The value of the signature header — `OpenWOP-Signature` / `X-openwop-Signature` (`"sha256=abc123…"`) or the legacy `openwop-Webhook-Signature` (`"v1=abc123…"`); see `readWebhookHeaders`.
+ * @param timestampHeader The value of the matching timestamp header (unix seconds as string).
  * @param rawBody The exact request body bytes the host POSTed.
  */
 export function verifyWebhookSignature(secret, signatureHeader, timestampHeader, rawBody, options = {}) {
-    // 1. Parse the signature header.
-    if (!signatureHeader.startsWith('v1=')) {
+    // 1. Parse the signature header — spec form `sha256=<hex>` (webhooks.md
+    //    §"Headers") or the legacy SDK form `v1=<hex>` (RFC 0165 §C.3).
+    const providedHex = parseSignatureValue(signatureHeader);
+    if (providedHex === null) {
         return { valid: false, reason: 'malformed_signature_header' };
     }
-    const providedHex = signatureHeader.slice(3);
     if (!/^[0-9a-f]+$/i.test(providedHex)) {
         return { valid: false, reason: 'malformed_signature_header' };
     }
@@ -90,8 +100,20 @@ export function signWebhookDelivery(secret, timestamp, rawBody) {
     const bodyStr = typeof rawBody === 'string' ? rawBody : rawBody.toString('utf8');
     const hex = createHmac('sha256', secret).update(`${timestamp}.${bodyStr}`, 'utf8').digest('hex');
     return {
-        signatureHeader: `v1=${hex}`,
+        signatureHeader: `sha256=${hex}`,
+        legacySignatureHeader: `v1=${hex}`,
         timestampHeader: String(timestamp),
+        headers: {
+            'OpenWOP-Signature': `sha256=${hex}`,
+            'OpenWOP-Timestamp': String(timestamp),
+            'OpenWOP-Signature-Algorithm': 'v1',
+            'X-openwop-Signature': `sha256=${hex}`,
+            'X-openwop-Timestamp': String(timestamp),
+            'X-openwop-Signature-Algorithm': 'v1',
+            'openwop-Webhook-Signature': `v1=${hex}`,
+            'openwop-Webhook-Timestamp': String(timestamp),
+        },
     };
 }
+export { WEBHOOK_HEADER_FAMILIES, parseSignatureValue, readWebhookHeaders } from './webhook-header-families.js';
 //# sourceMappingURL=webhook-helpers.js.map

package/dist/webhook-helpers.js.map

@@ -1 +1 @@
-{"version":3,"file":"webhook-helpers.js","sourceRoot":"","sources":["../src/webhook-helpers.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"webhook-helpers.js","sourceRoot":"","sources":["../src/webhook-helpers.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openwop/openwop",
-  "version": "1.7.0",
+  "version": "1.9.0",
   "description": "Production-ready TypeScript reference SDK for OpenWOP v1.0 compliant servers.",
   "repository": {
     "type": "git",
@@ -14,8 +14,14 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
+      "browser": "./dist/index.js",
       "import": "./dist/index.js"
-    }
+    },
+    "./webhooks": {
+      "types": "./dist/webhook-helpers.d.ts",
+      "import": "./dist/webhook-helpers.js"
+    },
+    "./package.json": "./package.json"
   },
   "files": [
     "dist",
@@ -40,5 +46,8 @@
   },
   "overrides": {
     "esbuild": "^0.25.0"
+  },
+  "browser": {
+    "./dist/webhook-helpers.js": "./dist/webhook-helpers.browser.js"
   }
 }

package/src/index.ts

@@ -188,6 +188,18 @@ export type { OpenwopCostAttributeName } from './cost-attribution.js';
 // HMAC-SHA256 + timestamp freshness window verification per
 // spec/v1/webhooks.md §"Signature recipe". Receivers MUST verify both
 // the HMAC AND the timestamp to defeat replay attacks.
+//
+// DEPRECATED ON THE BARREL (openwop-sdks#30). These re-exports are why a
+// browser consumer importing anything at all from `@openwop/openwop` dragged
+// in `node:crypto` and failed the build. Import them from
+// `@openwop/openwop/webhooks` instead; the barrel re-export is retained for
+// compatibility and will be removed in the next major.
+//
+// Until then the `browser` field in package.json substitutes a stub that
+// throws with an explanatory message, so a browser build succeeds and only a
+// browser CALL fails — which is the correct outcome either way, since the
+// subscription secret must never reach a browser.
+/** @deprecated Import from `@openwop/openwop/webhooks` — server-only; removed from the barrel in the next major. */
 export {
   DEFAULT_WEBHOOK_FRESHNESS_WINDOW_SECONDS,
   verifyWebhookSignature,
@@ -196,7 +208,12 @@ export {
 export type {
   VerifyWebhookSignatureOptions,
   VerifyWebhookOutcome,
+  SignedWebhookDelivery,
 } from './webhook-helpers.js';
+// RFC 0165 §C.3 — browser-safe (no Node builtin): which header family a
+// delivery carries, and the `sha256=` / legacy `v1=` value parser.
+export { WEBHOOK_HEADER_FAMILIES, parseSignatureValue, readWebhookHeaders } from './webhook-header-families.js';
+export type { WebhookHeaderRead } from './webhook-header-families.js';
 
 // Public-registry read helpers (SDK-5 close-out 2026-05-15). Read-only
 // typed client for the public node-pack registry at packs.openwop.dev

package/src/webhook-header-families.ts

@@ -0,0 +1,66 @@
+/**
+ * Webhook header families and signature-value parsing (RFC 0165 §C.3).
+ * Pure — no Node builtin — so both the server module (`webhook-helpers.ts`)
+ * and the browser stub re-export it. Verification itself stays server-only.
+ */
+
+/** Accepted signature-value prefixes, spec form first. */
+const SIGNATURE_VALUE_PREFIXES = ['sha256=', 'v1='] as const;
+
+/** `sha256=<hex>` or `v1=<hex>` → `<hex>`; anything else → null. */
+export function parseSignatureValue(value: string): string | null {
+  for (const p of SIGNATURE_VALUE_PREFIXES) {
+    if (value.startsWith(p)) {
+      const hex = value.slice(p.length);
+      return /^[0-9a-f]+$/i.test(hex) ? hex : null;
+    }
+  }
+  return null;
+}
+
+/**
+ * Header-name families a delivery may carry, in the order a receiver SHOULD
+ * prefer them (RFC 0165 §C.1): the v2-bound `OpenWOP-*` family, the v1
+ * canonical `X-openwop-*` family, then the legacy names this SDK used to
+ * document. Lookups are case-insensitive.
+ */
+export const WEBHOOK_HEADER_FAMILIES: ReadonlyArray<{ readonly signature: string; readonly timestamp: string; readonly algorithm?: string }> = [
+  { signature: 'OpenWOP-Signature', timestamp: 'OpenWOP-Timestamp', algorithm: 'OpenWOP-Signature-Algorithm' },
+  { signature: 'X-openwop-Signature', timestamp: 'X-openwop-Timestamp', algorithm: 'X-openwop-Signature-Algorithm' },
+  { signature: 'openwop-Webhook-Signature', timestamp: 'openwop-Webhook-Timestamp' },
+];
+
+export interface WebhookHeaderRead {
+  readonly signatureHeader: string;
+  readonly timestampHeader: string;
+  /** Which family was read: `openwop`, `x-openwop`, or `legacy`. */
+  readonly family: 'openwop' | 'x-openwop' | 'legacy';
+}
+
+/**
+ * Pick the signature + timestamp values out of a delivery's headers, first
+ * present family wins. Returns null when no family is complete. Pass a plain
+ * object (any casing) or a `Headers`-like with a `get` method.
+ */
+export function readWebhookHeaders(
+  headers: Record<string, string | string[] | undefined> | { get(name: string): string | null },
+): WebhookHeaderRead | null {
+  const get = (name: string): string | undefined => {
+    if (typeof (headers as { get?: unknown }).get === 'function') {
+      const v = (headers as { get(name: string): string | null }).get(name);
+      return v === null ? undefined : v;
+    }
+    const rec = headers as Record<string, string | string[] | undefined>;
+    const key = Object.keys(rec).find((k) => k.toLowerCase() === name.toLowerCase());
+    const v = key === undefined ? undefined : rec[key];
+    return Array.isArray(v) ? v[0] : v;
+  };
+  const families = ['openwop', 'x-openwop', 'legacy'] as const;
+  for (let i = 0; i < WEBHOOK_HEADER_FAMILIES.length; i++) {
+    const f = WEBHOOK_HEADER_FAMILIES[i]!;
+    const sig = get(f.signature);
+    const ts = get(f.timestamp);
+    if (sig !== undefined && ts !== undefined) return { signatureHeader: sig, timestampHeader: ts, family: families[i]! };
+  }
+  return null;
+}

package/src/webhook-helpers.browser.ts

@@ -0,0 +1,54 @@
+/**
+ * Browser substitute for `webhook-helpers.ts` (openwop-sdks#30).
+ *
+ * ## Why this file exists
+ *
+ * `webhook-helpers.ts` imports `node:crypto` for `createHmac` and
+ * `timingSafeEqual`. The package barrel re-exports it, and the `exports` map
+ * offers only `"."` — so a browser consumer importing ANYTHING from
+ * `@openwop/openwop` pulled the barrel, pulled the webhook helpers, and pulled
+ * `node:crypto`. Vite/Rollup then failed the BUILD with
+ *
+ *     "createHmac" is not exported by "__vite-browser-external"
+ *
+ * which names a bundler-internal shim rather than the real cause, so the error
+ * points nowhere useful. Reported 2026-05-26 and still reproducible against the
+ * published 1.7.0 fifteen months later.
+ *
+ * The `browser` field in package.json maps the Node module to this one, so the
+ * barrel is importable in a browser again. Webhook signature verification is a
+ * SERVER concern — a browser has no business holding the subscription secret —
+ * so the honest browser behaviour is to keep the import working and refuse the
+ * call, not to ship a second crypto implementation.
+ *
+ * ## Why it throws rather than returning a failure
+ *
+ * `verifyWebhookSignature` returning `{ ok: false }` in a browser would be a
+ * silent security downgrade: a caller that treats "not ok" as "reject the
+ * delivery" behaves identically whether the signature was forged or the
+ * platform simply could not check it. Those are different facts and only one of
+ * them is about the payload. Throwing keeps them distinguishable.
+ */
+
+const REASON =
+  'openwop: webhook signature helpers require Node\'s crypto (HMAC-SHA256 + timingSafeEqual) and are not available in a browser build. '
+  + 'Webhook verification is a server-side concern — the subscription secret must never reach a browser. '
+  + 'Import them on the server from "@openwop/openwop/webhooks".';
+
+/** @see spec/v1/webhooks.md §"Replay attack protection" */
+export const DEFAULT_WEBHOOK_FRESHNESS_WINDOW_SECONDS = 300;
+
+export function verifyWebhookSignature(): never {
+  throw new Error(REASON);
+}
+
+export function signWebhookDelivery(): never {
+  throw new Error(REASON);
+}
+
+// RFC 0165 §C.3 — the header-family readers need no Node builtin, so the
+// browser build carries the real implementations (a browser MAY inspect which
+// family a delivery carries; it still MUST NOT verify — no secret in a browser).
+export { WEBHOOK_HEADER_FAMILIES, parseSignatureValue, readWebhookHeaders } from './webhook-header-families.js';
+
+export type { VerifyWebhookSignatureOptions, VerifyWebhookOutcome, SignedWebhookDelivery, WebhookHeaderRead } from './webhook-helpers.js';

package/src/webhook-helpers.ts

@@ -4,15 +4,23 @@
  * timestamp freshness before accepting a delivery — verifying HMAC
  * alone leaves the receiver open to replay attacks.
  *
- * The canonical signing recipe:
+ * The canonical signing recipe (`webhooks.md` §"Headers"):
  *
  *     hmac = HMAC-SHA256(secret, `${timestamp}.${rawBody}`)
- *     header `openwop-Webhook-Signature: v1=<hmac-hex>`
- *     header `openwop-Webhook-Timestamp: <unix-seconds>`
+ *     header `X-openwop-Signature: sha256=<hmac-hex>`        (v1 canonical)
+ *     header `OpenWOP-Signature: sha256=<hmac-hex>`          (RFC 0165 §C.1, dual-emitted)
+ *     header `X-openwop-Timestamp` / `OpenWOP-Timestamp: <unix-seconds>`
+ *
+ * History (RFC 0165 §C.3): until 1.9.0 this helper read a header named
+ * `openwop-Webhook-Signature` carrying `v1=<hex>` — a name and value shape
+ * that appear in no spec file. A spec-conformant `sha256=` delivery failed
+ * verification outright. The helper now accepts BOTH value forms, and
+ * `readWebhookHeaders` picks the first present header family in spec order
+ * (`OpenWOP-*`, then `X-openwop-*`, then the legacy `openwop-Webhook-*`).
  *
  * Verification:
  *
- *   1. Parse the `v1=<hex>` value from the signature header.
+ *   1. Parse the `sha256=<hex>` (or legacy `v1=<hex>`) value from the signature header.
  *   2. Recompute `expected = HMAC-SHA256(secret, `${timestamp}.${rawBody}`)`.
  *   3. Compare using **constant-time** equality (timing-safe).
  *   4. Reject when `|now - timestamp|` exceeds the freshness window
@@ -26,6 +34,7 @@
  */
 
 import { createHmac, timingSafeEqual } from 'node:crypto';
+import { parseSignatureValue } from './webhook-header-families.js';
 
 /** Default freshness window per `spec/v1/webhooks.md` §"Replay attack resistance". */
 export const DEFAULT_WEBHOOK_FRESHNESS_WINDOW_SECONDS = 300;
@@ -58,8 +67,8 @@ export type VerifyWebhookOutcome =
  * signs the exact bytes it delivered.
  *
  * @param secret The pre-shared secret returned from `webhooks.register`.
- * @param signatureHeader The value of the `openwop-Webhook-Signature` header (e.g., `"v1=abc123…"`).
- * @param timestampHeader The value of the `openwop-Webhook-Timestamp` header (unix seconds as string).
+ * @param signatureHeader The value of the signature header — `OpenWOP-Signature` / `X-openwop-Signature` (`"sha256=abc123…"`) or the legacy `openwop-Webhook-Signature` (`"v1=abc123…"`); see `readWebhookHeaders`.
+ * @param timestampHeader The value of the matching timestamp header (unix seconds as string).
  * @param rawBody The exact request body bytes the host POSTed.
  */
 export function verifyWebhookSignature(
@@ -69,11 +78,12 @@ export function verifyWebhookSignature(
   rawBody: string | Buffer,
   options: VerifyWebhookSignatureOptions = {},
 ): VerifyWebhookOutcome {
-  // 1. Parse the signature header.
-  if (!signatureHeader.startsWith('v1=')) {
+  // 1. Parse the signature header — spec form `sha256=<hex>` (webhooks.md
+  //    §"Headers") or the legacy SDK form `v1=<hex>` (RFC 0165 §C.3).
+  const providedHex = parseSignatureValue(signatureHeader);
+  if (providedHex === null) {
     return { valid: false, reason: 'malformed_signature_header' };
   }
-  const providedHex = signatureHeader.slice(3);
   if (!/^[0-9a-f]+$/i.test(providedHex)) {
     return { valid: false, reason: 'malformed_signature_header' };
   }
@@ -111,6 +121,16 @@ export function verifyWebhookSignature(
   return { valid: true };
 }
 
+export interface SignedWebhookDelivery {
+  /** Spec form: `sha256=<hex>` (webhooks.md §"Headers"). */
+  readonly signatureHeader: string;
+  /** Legacy form this SDK used to emit: `v1=<hex>` (RFC 0165 §C.3). */
+  readonly legacySignatureHeader: string;
+  readonly timestampHeader: string;
+  /** Every header a host should send during the RFC 0165 overlap, by exact name. */
+  readonly headers: Readonly<Record<string, string>>;
+}
+
 /**
  * Compute the canonical webhook signature for a payload — useful when
  * implementing a host (forward direction) OR when generating test
@@ -121,11 +141,25 @@ export function signWebhookDelivery(
   secret: string,
   timestamp: number,
   rawBody: string | Buffer,
-): { signatureHeader: string; timestampHeader: string } {
+): SignedWebhookDelivery {
   const bodyStr = typeof rawBody === 'string' ? rawBody : rawBody.toString('utf8');
   const hex = createHmac('sha256', secret).update(`${timestamp}.${bodyStr}`, 'utf8').digest('hex');
   return {
-    signatureHeader: `v1=${hex}`,
+    signatureHeader: `sha256=${hex}`,
+    legacySignatureHeader: `v1=${hex}`,
     timestampHeader: String(timestamp),
+    headers: {
+      'OpenWOP-Signature': `sha256=${hex}`,
+      'OpenWOP-Timestamp': String(timestamp),
+      'OpenWOP-Signature-Algorithm': 'v1',
+      'X-openwop-Signature': `sha256=${hex}`,
+      'X-openwop-Timestamp': String(timestamp),
+      'X-openwop-Signature-Algorithm': 'v1',
+      'openwop-Webhook-Signature': `v1=${hex}`,
+      'openwop-Webhook-Timestamp': String(timestamp),
+    },
   };
 }
+
+export { WEBHOOK_HEADER_FAMILIES, parseSignatureValue, readWebhookHeaders } from './webhook-header-families.js';
+export type { WebhookHeaderRead } from './webhook-header-families.js';