@openwop/openwop 1.8.0 → 2.0.0

package/dist/webhook-helpers.js

@@ -1,72 +1,79 @@
 /**
- * Webhook delivery-verification helpers per `spec/v1/webhooks.md`
- * §"Signature recipe". Receivers MUST verify both the HMAC AND the
- * timestamp freshness before accepting a delivery — verifying HMAC
- * alone leaves the receiver open to replay attacks.
+ * Webhook delivery-verification helpers per `spec/v2/core/webhooks.md`
+ * §Verification. Receivers MUST verify both the HMAC AND the timestamp
+ * freshness before accepting a delivery — verifying HMAC alone leaves the
+ * receiver open to replay attacks.
  *
- * The canonical signing recipe:
+ * The 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 `OpenWOP-Signature: sha256=<hmac-hex>`
+ *     header `OpenWOP-Timestamp: <unix-seconds>`
+ *     header `OpenWOP-Signature-Algorithm: v1`
+ *
+ * A host advertising both majors sends the `X-openwop-*` family beside it
+ * with identical values through the overlap; `readWebhookHeaders` accepts
+ * either family. The SDK-only `openwop-Webhook-*` names and the `v1=<hex>`
+ * value form were removed in v2 (headers.md §Removed).
  *
  * Verification:
  *
- *   1. Parse the `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
- *      (default 5 minutes per `webhooks.md`'s recommendation).
+ *   1. Parse the `sha256=<hex>` value from the signature header.
+ *   2. Reject an unrecognized `OpenWOP-Signature-Algorithm` value (MUST).
+ *   3. Reject a timestamp more than ±window from the clock (default 5 min).
+ *   4. Recompute `HMAC-SHA256(`${timestamp}.${rawBody}`, secret)` and compare
+ *      in constant time.
  *
- * Implementation note: this helper uses `node:crypto`'s `timingSafeEqual`
- * for the comparison. The browser-side equivalent (Web Crypto's
- * `subtle.verify`) is not wrapped here — the SDK's runtime is Node.
+ * Implementation note: this helper uses `node:crypto`'s `timingSafeEqual`.
+ * The browser build substitutes a stub that throws (see
+ * `webhook-helpers.browser.ts`).
  *
  * @module @openwop/openwop/webhook-helpers
  */
 import { createHmac, timingSafeEqual } from 'node:crypto';
-/** Default freshness window per `spec/v1/webhooks.md` §"Replay attack resistance". */
+import { parseSignatureValue, WEBHOOK_SIGNATURE_ALGORITHMS } from './webhook-header-families.js';
+/** Default freshness window per webhooks.md §Verification (±5 minutes). */
 export const DEFAULT_WEBHOOK_FRESHNESS_WINDOW_SECONDS = 300;
 /**
- * Verify a webhook delivery per `spec/v1/webhooks.md` §"Signature
- * recipe". Returns `{ valid: true }` on success; otherwise
+ * Verify a webhook delivery. Returns `{ valid: true }` on success; otherwise
  * `{ valid: false, reason }` so callers can log + alert appropriately.
  *
- * Callers MUST pass the **raw** body bytes — JSON-parsed-then-
- * re-serialized bodies will fail verification because the host
- * signs the exact bytes it delivered.
+ * Callers MUST pass the **raw** body bytes — JSON-parsed-then-re-serialized
+ * bodies fail verification because the host 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 secret The subscription secret.
+ * @param signatureHeader `OpenWOP-Signature` / `X-openwop-Signature` (`"sha256=abc123…"`); see `readWebhookHeaders`.
+ * @param timestampHeader 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 — `sha256=<hex>` only.
+    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' };
+    // 2. Reject an unrecognized scheme.
+    if (options.algorithmHeader !== undefined &&
+        !WEBHOOK_SIGNATURE_ALGORITHMS.includes(options.algorithmHeader)) {
+        return { valid: false, reason: 'unsupported_signature_algorithm' };
     }
-    // 2. Parse the timestamp.
+    // 3. Parse the timestamp.
     const timestamp = Number(timestampHeader);
     if (!Number.isInteger(timestamp) || timestamp <= 0) {
         return { valid: false, reason: 'malformed_timestamp_header' };
     }
-    // 3. Freshness check.
+    // 4. Freshness check.
     const window = options.freshnessWindowSeconds ?? DEFAULT_WEBHOOK_FRESHNESS_WINDOW_SECONDS;
     if (window > 0) {
         const now = options.nowSeconds ?? Math.floor(Date.now() / 1000);
         const delta = now - timestamp;
         if (delta > window)
             return { valid: false, reason: 'timestamp_expired' };
-        // Allow small future skew (within the window) but reject far-future timestamps.
         if (delta < -window)
             return { valid: false, reason: 'timestamp_too_far_in_future' };
     }
-    // 4. Recompute + constant-time compare.
+    // 5. Recompute + constant-time compare.
     const bodyStr = typeof rawBody === 'string' ? rawBody : rawBody.toString('utf8');
     const signedBytes = `${timestamp}.${bodyStr}`;
     const expectedHex = createHmac('sha256', secret).update(signedBytes, 'utf8').digest('hex');
@@ -82,16 +89,24 @@ export function verifyWebhookSignature(secret, signatureHeader, timestampHeader,
 }
 /**
  * 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.
+ * implementing a host (forward direction) OR when generating test fixtures.
+ * Receivers verify via `verifyWebhookSignature`; this is the inverse.
  */
 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}`,
         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',
+        },
     };
 }
+export { WEBHOOK_HEADER_FAMILIES, WEBHOOK_SIGNATURE_ALGORITHMS, 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,11 +1,11 @@
 {
   "name": "@openwop/openwop",
-  "version": "1.8.0",
-  "description": "Production-ready TypeScript reference SDK for OpenWOP v1.0 compliant servers.",
+  "version": "2.0.0",
+  "description": "TypeScript reference SDK for OpenWOP v2 hosts — bare-origin unversioned paths, OpenWOP-Version negotiation, the closed discovery root, and the generated error-code registry.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/openwop/openwop-sdks.git",
-    "directory": "sdk/typescript"
+    "directory": "sdk/typescript-v2"
   },
   "license": "Apache-2.0",
   "type": "module",
@@ -33,8 +33,10 @@
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit",
+    "generate": "node scripts/generate.mjs",
+    "generate:check": "node scripts/generate.mjs --check",
     "test": "vitest run",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run generate:check && npm run build"
   },
   "engines": {
     "node": ">=20"