@theholocron/holocron-plugin-clerk 2.0.0-alpha.59 → 2.0.0-alpha.60

package/dist/index.mjs

@@ -1,5 +1,6 @@
 import { AuthError, ProviderApiError, WebhookVerificationError, createResolveToken } from "@theholocron/cli";
 import { createClerkClient } from "@theholocron/clerk-client";
+import { createHmac, timingSafeEqual } from "node:crypto";
 //#region src/auth.ts
 const resolveToken = createResolveToken({
 	envName: "HOLOCRON_CLERK_SECRET_KEY",
@@ -98,27 +99,23 @@ function isAlreadyExistsError(err) {
 //#region src/parse-webhook.ts
 /**
 * Translates a Clerk webhook delivery into the normalized `AuthEvent`
-* shape defined in `@theholocron/cli`. The first concrete example of
-* the cross-provider sync pattern (see `AuthEvent` JSDoc in core).
+* shape defined in `@theholocron/cli`, with full Svix HMAC-SHA256
+* signature verification (closes #80).
 *
-* Status: signature SHIPPED, body STUBBED. Real Svix signature
-* verification (HMAC-SHA256 over `svix-id.svix-timestamp.body` with
-* the `whsec_…` signing secret, base64-decoded) lands in a follow-up
-* (tracked at #80). For now, parseWebhook trusts the request and
-* focuses on shape translation — usable in environments where
-* signature verification happens upstream (e.g., Vercel middleware,
-* an API gateway), and an explicit error in production-grade
-* deployments until the verification body lands.
-*
-* Reference event shapes:
-*   https://clerk.com/docs/integrations/webhooks/overview
-*   https://clerk.com/docs/reference/backend-api/tag/Webhooks
+* Verification algorithm (https://docs.svix.com/receiving/verifying-payloads/how-manual):
+*   1. Require svix-id, svix-timestamp, svix-signature headers
+*   2. Reject if svix-timestamp is outside the ±5-minute replay window
+*   3. Decode the whsec_<base64> signing secret
+*   4. Compute HMAC-SHA256(secretBytes, "${id}.${timestamp}.${body}")
+*   5. Constant-time compare against each v1,<base64> signature in the
+*      space-separated svix-signature header (supports key rotation)
 */
 const CLERK_TO_NORMALIZED = {
 	"user.created": "user.created",
 	"user.updated": "user.updated",
 	"user.deleted": "user.deleted"
 };
+const REPLAY_WINDOW_SECONDS = 300;
 async function parseWebhook(input) {
 	await verifySignature(input);
 	const bodyStr = typeof input.body === "string" ? input.body : input.body.toString("utf8");
@@ -144,22 +141,37 @@ async function parseWebhook(input) {
 		occurredAt
 	};
 }
-/**
-* Stub for Svix signature verification. The real implementation
-* lands at #80 and will:
-*
-*   1. Read svix-id, svix-timestamp, svix-signature headers
-*   2. Verify svix-timestamp is within the replay window (±5 min)
-*   3. Compute HMAC-SHA256(<signing_secret>, `${id}.${timestamp}.${body}`)
-*   4. Compare (constant-time) against the base64 sig in svix-signature
-*
-* For now: throw WebhookVerificationError when the signing secret is
-* missing, so consumers see the contract; let the call through
-* otherwise (signature-validation TODO).
-*/
 async function verifySignature(input) {
 	if (!input.signingSecret) throw new WebhookVerificationError("Clerk webhook signingSecret is required (use the Svix whsec_… value from the Clerk dashboard)");
-	return Promise.resolve();
+	const lower = (s) => s.toLowerCase();
+	const h = (name) => {
+		const target = lower(name);
+		for (const [k, v] of Object.entries(input.headers)) if (lower(k) === target) return Array.isArray(v) ? v[0] : v;
+	};
+	const svixId = h("svix-id");
+	const svixTimestamp = h("svix-timestamp");
+	const svixSignature = h("svix-signature");
+	if (!svixId || !svixTimestamp || !svixSignature) throw new WebhookVerificationError("Missing required Svix headers: svix-id, svix-timestamp, svix-signature");
+	const ts = parseInt(svixTimestamp, 10);
+	if (isNaN(ts)) throw new WebhookVerificationError(`Invalid svix-timestamp: "${svixTimestamp}"`);
+	const nowSeconds = Math.floor(Date.now() / 1e3);
+	if (Math.abs(nowSeconds - ts) > REPLAY_WINDOW_SECONDS) throw new WebhookVerificationError(`Message timestamp is outside the ${REPLAY_WINDOW_SECONDS / 60}-minute replay window`);
+	const secretBase64 = input.signingSecret.startsWith("whsec_") ? input.signingSecret.slice(6) : input.signingSecret;
+	const secretBytes = Buffer.from(secretBase64, "base64");
+	const toSign = `${svixId}.${svixTimestamp}.${typeof input.body === "string" ? input.body : input.body.toString("utf8")}`;
+	const computed = createHmac("sha256", secretBytes).update(toSign).digest();
+	if (!svixSignature.split(" ").some((sig) => {
+		const comma = sig.indexOf(",");
+		if (comma === -1 || sig.slice(0, comma) !== "v1") return false;
+		let sigBytes;
+		try {
+			sigBytes = Buffer.from(sig.slice(comma + 1), "base64");
+		} catch {
+			return false;
+		}
+		if (sigBytes.length !== computed.length) return false;
+		return timingSafeEqual(sigBytes, computed);
+	})) throw new WebhookVerificationError("Svix signature verification failed");
 }
 //#endregion
 //#region src/verify-token.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/holocron-plugin-clerk",
-  "version": "2.0.0-alpha.59",
+  "version": "2.0.0-alpha.60",
   "description": "Holocron plugin for Clerk. Implements the auth capability against Clerk's Backend REST API.",
   "homepage": "https://github.com/theholocron/holocron/tree/main/packages/holocron-plugin-clerk#readme",
   "bugs": "https://github.com/theholocron/holocron/issues",
@@ -22,7 +22,7 @@
   },
   "peerDependencies": {
     "@theholocron/clerk-client": "^0.11.3",
-    "@theholocron/cli": "2.0.0-alpha.59"
+    "@theholocron/cli": "2.0.0-alpha.60"
   },
   "devDependencies": {
     "@theholocron/clerk-client": "^0.11.3",
@@ -40,7 +40,7 @@
     "tsx": "^4.22.4",
     "typescript": "^5.9.3",
     "vitest": "^4.1.10",
-    "@theholocron/cli": "2.0.0-alpha.59"
+    "@theholocron/cli": "2.0.0-alpha.60"
   },
   "publishConfig": {
     "access": "public"