@arkyc/webhooks 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,3 @@
+import { VerifyWebhookInput, WebhookSigner } from "./signing.mjs";
+import { BuildWebhookPayloadInput, WebhookPayload } from "./payload.mjs";
+export { BuildWebhookPayloadInput, VerifyWebhookInput, WebhookPayload, WebhookSigner };

package/dist/index.mjs

@@ -0,0 +1,3 @@
+import { WebhookSigner } from "./signing.mjs";
+import { WebhookPayload } from "./payload.mjs";
+export { WebhookPayload, WebhookSigner };

package/dist/payload.d.mts

@@ -0,0 +1,33 @@
+import { DecisionReason, VerificationStatus, WebhookChecks, WebhookEvent, WebhookEventName } from "@arkyc/types";
+
+//#region src/payload.d.ts
+/** The data needed to assemble a {@link WebhookEvent} body. */
+interface BuildWebhookPayloadInput {
+  event: WebhookEventName;
+  sessionId: string;
+  organizationId: string;
+  projectId: string;
+  userReference: string | null;
+  status: VerificationStatus;
+  checks: WebhookChecks;
+  decisionReason: DecisionReason | null;
+  /** Signed inline-image URLs for captured assets (when any exist). */
+  assets?: Record<string, string> | null;
+  /** ISO-8601 timestamp the event occurred. */
+  createdAt: string;
+}
+/**
+ * Assemble the JSON body delivered to a webhook endpoint.
+ */
+declare class WebhookPayload {
+  /**
+   * Build the JSON body delivered to a webhook endpoint (matches the spec shape).
+   *
+   * @param input
+   * @returns
+   */
+  static build(input: BuildWebhookPayloadInput): WebhookEvent;
+}
+//#endregion
+export { BuildWebhookPayloadInput, WebhookPayload };
+//# sourceMappingURL=payload.d.mts.map

package/dist/payload.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payload.d.mts","names":[],"sources":["../src/payload.ts"],"mappings":";;;;UAGiB,wBAAA;EACf,KAAA,EAAO,gBAAA;EACP,SAAA;EACA,cAAA;EACA,SAAA;EACA,aAAA;EACA,MAAA,EAAQ,kBAAA;EACR,MAAA,EAAQ,aAAA;EACR,cAAA,EAAgB,cAAA;EAED;EAAf,MAAA,GAAS,MAAA;EATT;EAWA,SAAA;AAAA;;;;cAMW,cAAA;EAZH;;;;;;EAAA,OAmBD,KAAA,CAAM,KAAA,EAAO,wBAAA,GAA2B,YAAY;AAAA"}

package/dist/payload.mjs

@@ -0,0 +1,30 @@
+//#region src/payload.ts
+/**
+* Assemble the JSON body delivered to a webhook endpoint.
+*/
+var WebhookPayload = class {
+	/**
+	* Build the JSON body delivered to a webhook endpoint (matches the spec shape).
+	*
+	* @param input
+	* @returns
+	*/
+	static build(input) {
+		return {
+			event: input.event,
+			session_id: input.sessionId,
+			organization_id: input.organizationId,
+			project_id: input.projectId,
+			user_reference: input.userReference,
+			status: input.status,
+			checks: input.checks,
+			decision_reason: input.decisionReason,
+			assets: input.assets ?? null,
+			created_at: input.createdAt
+		};
+	}
+};
+//#endregion
+export { WebhookPayload };
+
+//# sourceMappingURL=payload.mjs.map

package/dist/payload.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"payload.mjs","names":[],"sources":["../src/payload.ts"],"sourcesContent":["import type { DecisionReason, VerificationStatus, WebhookChecks, WebhookEvent, WebhookEventName } from '@arkyc/types'\n\n/** The data needed to assemble a {@link WebhookEvent} body. */\nexport interface BuildWebhookPayloadInput {\n  event: WebhookEventName\n  sessionId: string\n  organizationId: string\n  projectId: string\n  userReference: string | null\n  status: VerificationStatus\n  checks: WebhookChecks\n  decisionReason: DecisionReason | null\n  /** Signed inline-image URLs for captured assets (when any exist). */\n  assets?: Record<string, string> | null\n  /** ISO-8601 timestamp the event occurred. */\n  createdAt: string\n}\n\n/**\n * Assemble the JSON body delivered to a webhook endpoint.\n */\nexport class WebhookPayload {\n  /**\n   * Build the JSON body delivered to a webhook endpoint (matches the spec shape).\n   *\n   * @param input\n   * @returns\n   */\n  static build(input: BuildWebhookPayloadInput): WebhookEvent {\n    return {\n      event: input.event,\n      session_id: input.sessionId,\n      organization_id: input.organizationId,\n      project_id: input.projectId,\n      user_reference: input.userReference,\n      status: input.status,\n      checks: input.checks,\n      decision_reason: input.decisionReason,\n      assets: input.assets ?? null,\n      created_at: input.createdAt,\n    }\n  }\n}\n"],"mappings":";;;;AAqBA,IAAa,iBAAb,MAA4B;;;;;;;CAO1B,OAAO,MAAM,OAA+C;EAC1D,OAAO;GACL,OAAO,MAAM;GACb,YAAY,MAAM;GAClB,iBAAiB,MAAM;GACvB,YAAY,MAAM;GAClB,gBAAgB,MAAM;GACtB,QAAQ,MAAM;GACd,QAAQ,MAAM;GACd,iBAAiB,MAAM;GACvB,QAAQ,MAAM,UAAU;GACxB,YAAY,MAAM;EACpB;CACF;AACF"}

package/dist/signing.d.mts

@@ -0,0 +1,49 @@
+//#region src/signing.d.ts
+/** Inputs for verifying a received webhook signature. */
+interface VerifyWebhookInput {
+  /** Raw request body as received. */
+  payload: string;
+  /** The endpoint's signing secret. */
+  secret: string;
+  /** Signature from the `X-Arkyc-Signature` header. */
+  signature: string;
+  /** Timestamp from the `X-Arkyc-Timestamp` header (unix seconds). */
+  timestamp: number;
+  /** Allowed clock skew in seconds (default 300). */
+  toleranceSec?: number;
+  /** Injected clock (epoch ms) — pure + testable. */
+  now?: number;
+}
+/**
+ * Sign and verify webhook deliveries (HMAC-SHA256, Stripe-style).
+ */
+declare class WebhookSigner {
+  /** Header carrying the HMAC signature on a delivered webhook. */
+  static readonly SIGNATURE_HEADER = "X-Arkyc-Signature";
+  /** Header carrying the unix-seconds timestamp the signature covers. */
+  static readonly TIMESTAMP_HEADER = "X-Arkyc-Timestamp";
+  /** Default tolerance (seconds) for the timestamp when verifying. */
+  static readonly DEFAULT_TOLERANCE_SEC = 300;
+  /**
+   * Compute the HMAC-SHA256 signature for a webhook body.
+   *
+   * The signed message is `${timestamp}.${payload}` (Stripe-style), so a captured
+   * body can't be replayed under a different timestamp.
+   *
+   * @param payload    The exact JSON string that will be sent as the body.
+   * @param secret     The endpoint's signing secret.
+   * @param timestamp  Unix seconds the signature is bound to.
+   */
+  static sign(payload: string, secret: string, timestamp: number): string;
+  /**
+   * Verify a webhook signature and reject stale/forged deliveries: the timestamp
+   * must be within tolerance and the HMAC must match (constant-time compare).
+   *
+   * @param input
+   * @returns
+   */
+  static verify(input: VerifyWebhookInput): boolean;
+}
+//#endregion
+export { VerifyWebhookInput, WebhookSigner };
+//# sourceMappingURL=signing.d.mts.map

package/dist/signing.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signing.d.mts","names":[],"sources":["../src/signing.ts"],"mappings":";;UAGiB,kBAAA;EAAkB;EAEjC,OAAA;EAFiC;EAIjC,MAAA;EAAA;EAEA,SAAA;EAEA;EAAA,SAAA;EAIA;EAFA,YAAA;EAEG;EAAH,GAAA;AAAA;;;;cAMW,aAAA;EAQK;EAAA,gBANA,gBAAA;EAkBJ;EAAA,gBAfI,gBAAA;EAe6B;EAAA,gBAZ7B,qBAAA;EAuBK;;;AAAkB;;;;;;;EAAlB,OAXd,IAAA,CAAK,OAAA,UAAiB,MAAA,UAAgB,SAAA;;;;;;;;SAWtC,MAAA,CAAO,KAAA,EAAO,kBAAkB;AAAA"}

package/dist/signing.mjs

@@ -0,0 +1,47 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+//#region src/signing.ts
+/**
+* Sign and verify webhook deliveries (HMAC-SHA256, Stripe-style).
+*/
+var WebhookSigner = class WebhookSigner {
+	/** Header carrying the HMAC signature on a delivered webhook. */
+	static SIGNATURE_HEADER = "X-Arkyc-Signature";
+	/** Header carrying the unix-seconds timestamp the signature covers. */
+	static TIMESTAMP_HEADER = "X-Arkyc-Timestamp";
+	/** Default tolerance (seconds) for the timestamp when verifying. */
+	static DEFAULT_TOLERANCE_SEC = 300;
+	/**
+	* Compute the HMAC-SHA256 signature for a webhook body.
+	*
+	* The signed message is `${timestamp}.${payload}` (Stripe-style), so a captured
+	* body can't be replayed under a different timestamp.
+	*
+	* @param payload    The exact JSON string that will be sent as the body.
+	* @param secret     The endpoint's signing secret.
+	* @param timestamp  Unix seconds the signature is bound to.
+	*/
+	static sign(payload, secret, timestamp) {
+		return createHmac("sha256", secret).update(`${timestamp}.${payload}`).digest("hex");
+	}
+	/**
+	* Verify a webhook signature and reject stale/forged deliveries: the timestamp
+	* must be within tolerance and the HMAC must match (constant-time compare).
+	*
+	* @param input
+	* @returns
+	*/
+	static verify(input) {
+		const tolerance = input.toleranceSec ?? WebhookSigner.DEFAULT_TOLERANCE_SEC;
+		const nowSec = Math.floor((input.now ?? Date.now()) / 1e3);
+		if (!Number.isFinite(input.timestamp)) return false;
+		if (Math.abs(nowSec - input.timestamp) > tolerance) return false;
+		const expected = WebhookSigner.sign(input.payload, input.secret, input.timestamp);
+		const a = Buffer.from(input.signature);
+		const b = Buffer.from(expected);
+		return a.length === b.length && timingSafeEqual(a, b);
+	}
+};
+//#endregion
+export { WebhookSigner };
+
+//# sourceMappingURL=signing.mjs.map

package/dist/signing.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"signing.mjs","names":[],"sources":["../src/signing.ts"],"sourcesContent":["import { createHmac, timingSafeEqual } from 'node:crypto'\n\n/** Inputs for verifying a received webhook signature. */\nexport interface VerifyWebhookInput {\n  /** Raw request body as received. */\n  payload: string\n  /** The endpoint's signing secret. */\n  secret: string\n  /** Signature from the `X-Arkyc-Signature` header. */\n  signature: string\n  /** Timestamp from the `X-Arkyc-Timestamp` header (unix seconds). */\n  timestamp: number\n  /** Allowed clock skew in seconds (default 300). */\n  toleranceSec?: number\n  /** Injected clock (epoch ms) — pure + testable. */\n  now?: number\n}\n\n/**\n * Sign and verify webhook deliveries (HMAC-SHA256, Stripe-style).\n */\nexport class WebhookSigner {\n  /** Header carrying the HMAC signature on a delivered webhook. */\n  static readonly SIGNATURE_HEADER = 'X-Arkyc-Signature'\n\n  /** Header carrying the unix-seconds timestamp the signature covers. */\n  static readonly TIMESTAMP_HEADER = 'X-Arkyc-Timestamp'\n\n  /** Default tolerance (seconds) for the timestamp when verifying. */\n  static readonly DEFAULT_TOLERANCE_SEC = 300\n\n  /**\n   * Compute the HMAC-SHA256 signature for a webhook body.\n   *\n   * The signed message is `${timestamp}.${payload}` (Stripe-style), so a captured\n   * body can't be replayed under a different timestamp.\n   *\n   * @param payload    The exact JSON string that will be sent as the body.\n   * @param secret     The endpoint's signing secret.\n   * @param timestamp  Unix seconds the signature is bound to.\n   */\n  static sign(payload: string, secret: string, timestamp: number): string {\n    return createHmac('sha256', secret).update(`${timestamp}.${payload}`).digest('hex')\n  }\n\n  /**\n   * Verify a webhook signature and reject stale/forged deliveries: the timestamp\n   * must be within tolerance and the HMAC must match (constant-time compare).\n   *\n   * @param input\n   * @returns\n   */\n  static verify(input: VerifyWebhookInput): boolean {\n    const tolerance = input.toleranceSec ?? WebhookSigner.DEFAULT_TOLERANCE_SEC\n    const nowSec = Math.floor((input.now ?? Date.now()) / 1000)\n    if (!Number.isFinite(input.timestamp)) return false\n    if (Math.abs(nowSec - input.timestamp) > tolerance) return false\n\n    const expected = WebhookSigner.sign(input.payload, input.secret, input.timestamp)\n    const a = Buffer.from(input.signature)\n    const b = Buffer.from(expected)\n\n    return a.length === b.length && timingSafeEqual(a, b)\n  }\n}\n"],"mappings":";;;;;AAqBA,IAAa,gBAAb,MAAa,cAAc;;CAEzB,OAAgB,mBAAmB;;CAGnC,OAAgB,mBAAmB;;CAGnC,OAAgB,wBAAwB;;;;;;;;;;;CAYxC,OAAO,KAAK,SAAiB,QAAgB,WAA2B;EACtE,OAAO,WAAW,UAAU,MAAM,CAAC,CAAC,OAAO,GAAG,UAAU,GAAG,SAAS,CAAC,CAAC,OAAO,KAAK;CACpF;;;;;;;;CASA,OAAO,OAAO,OAAoC;EAChD,MAAM,YAAY,MAAM,gBAAgB,cAAc;EACtD,MAAM,SAAS,KAAK,OAAO,MAAM,OAAO,KAAK,IAAI,KAAK,GAAI;EAC1D,IAAI,CAAC,OAAO,SAAS,MAAM,SAAS,GAAG,OAAO;EAC9C,IAAI,KAAK,IAAI,SAAS,MAAM,SAAS,IAAI,WAAW,OAAO;EAE3D,MAAM,WAAW,cAAc,KAAK,MAAM,SAAS,MAAM,QAAQ,MAAM,SAAS;EAChF,MAAM,IAAI,OAAO,KAAK,MAAM,SAAS;EACrC,MAAM,IAAI,OAAO,KAAK,QAAQ;EAE9B,OAAO,EAAE,WAAW,EAAE,UAAU,gBAAgB,GAAG,CAAC;CACtD;AACF"}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@arkyc/webhooks",
+  "version": "1.0.0",
+  "description": "Webhook signing, verification, and payload building",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@arkyc/types": "^1.0.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "eslint src",
+    "clean": "rm -rf dist"
+  }
+}